SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsinit-shadcn-docs-nuxt

init-shadcn-docs-nuxt

Frontend & websites

View repository

Updated 10-16 06:52

About this skill

Initialize shadcn-docs-nuxt component library documentation

With the goal of "minimal usable + fast and stable", establish a long-term maintainable shadcn-docs-nuxt documentation site for any project.

This skill is split into three layers:

  • SKILL.md — navigation and workflow
  • references/ — troubleshooting manual and configuration guide
  • templates/ — directly copyable code templates (with complete comments; the comments are the documentation)

During execution, proceed according to the workflow; when encountering configuration details, consult reference; when code is needed, read template directly.

Template file index (templates/)

Code templates contain complete explanatory comments;the comments record the root cause of each configuration item, the consequences of not configuring it, and historical incidents. When using them, read the template files directly; do not skip the comments.

Template file Corresponding documentation site file Description
templates/nuxt.config.minimal.ts nuxt.config.ts Minimal startup skeleton
templates/nuxt.config.full.ts nuxt.config.ts Production baseline (Nitro trace retained by default)
templates/app.config.ts app.config.ts Site metadata and UI configuration
templates/tailwind.config.js tailwind.config.js Complete Tailwind + shadcn-vue theme
templates/assets/css/tailwind.css assets/css/tailwind.css CSS entry + light/dark theme variables
templates/assets/css/main.css assets/css/main.css Custom style example
templates/shims/debug.ts shims/debug.ts debug ESM compatibility shim
templates/workspace-aliases.ts workspace-aliases.ts Component library source alias function
templates/plugins/ui-lib.ts plugins/xxx.ts Nuxt Plugin registration pattern
templates/package.json package.json Dependencies and scripts baseline
templates/prettierrc.json .prettierrc MDC protection (fallback solution)
templates/prettierignore .prettierignore MDC protection (primary solution)

Reference documentation index (references/)

File Content
references/nuxt-config.md On-demand patch strategy, list of items not to modify
references/compat.md ESM/CJS compatibility quick reference table, troubleshooting order, common misjudgment table
references/tailwind-css.md content scanning rules, CSS variable format, common style issue troubleshooting
references/mdc-prettier.md MDC standard syntax, comparison of 5 incorrect writing styles, hydration mismatch causal chain
references/windows.md Build false hang, child process chain cleanup, EPERM file lock, single-process reproduction method
references/workspace.md Alias order pitfalls, dependency matrix, plugin registration, i18n monolingual, OG Image, directory structure
references/incident-repair.md Nuxt Content/H3 version drift, prerender hook history and layered build failure troubleshooting
references/dependency-triage.md Dependency hoisting layer troubleshooting, packageExtensions/overrides/patch decisions, optimizeDeps blind spots, fork governance, platform binary tracking
references/ssr-hydration.md Hydration diagnostic toolchain, non-SSR-safe package isolation techniques, hoisted component resolution pitfalls, HTTP 200 illusion, SSR acceptance checklist
references/production-graph-and-runtime-closure.md production graph、final Nitro OOM、standalone MODULE_NOT_FOUND, Turbo cache and artifact acceptance
references/README.md Signal navigation and migration ledger for the nine current references

Core principles (6 iron rules)

  1. Keep it lean：nuxt.config.ts and app.config.ts should be minimized first; do not pile on features first.
  2. Get it running before beautifying: prioritize ensuring dev / build is stable, then do styling and content expansion.
  3. Fix the runtime chain before fixing styles: for interaction anomalies (dark mode, sidebar collapse failure), check hydration and module import errors first; do not change CSS first.
  4. Avoid incorrect extensions: do not immediately tinker with i18n / icon customization solutions; first use the template's default usable path.
  5. Strict content syntax: MDC container syntax must be standardized; see references/mdc-prettier.md。
  6. Production closure: evidence first, configuration second：Vercel READY It only means the deployment orchestration is complete, not that the Function runtime is available; the deployment package manifest, final artifact, remote requests, and runtime logs must be chained into an evidence chain.

Hard constraints from historical incidents (22 memories)

When executing this skill,you must by default carry these "already happened" incident memories：

  1. Do not assume the workspace component library has already been built first; the documentation site needs to be able to start directly from source. → See references/workspace.md
  2. Do not first attribute interaction failure to styles; first rule out hydration being interrupted by a module import error. → See references/compat.md
  3. Do not let prettier rewrite content/**/\*.md 's MDC structure. → See references/mdc-prettier.md
  4. Do not directly judge "logs stopped" as "process hung" under Windows, first investigate residual child processes. → See references/windows.md
  5. Do not rewrite the i18n / icon system right from the start; first get the template's default path working. → See references/nuxt-config.md
  6. Do not directly enable the ogImage module; it will trigger vue.runtime.mjs does not provide an export named toValue 's 500 error. → See references/nuxt-config.md
  7. Core runtime packages must be pinned according to the compatibility matrix: at minimum review simultaneously shadcn-docs-nuxt、@ztl-uwu/nuxt-content、nuxt、h3, and do not look only at the theme's transitive dependency scope.
  8. prerender:routes is not an unconditional disable item, but a historical workaround: it was once used to mitigate the Windows build long tail, but for document-driven Nuxt Content it causes the content database to be empty; it can only be discussed when it is confirmed that the project does not depend on Content prerender and equivalent verification has been completed. → See references/incident-repair.md
  9. final Nitro OOM and standalone MODULE_NOT_FOUND must return to the first failing gate: the former requires measuring the heap and artifact stage, the latter requires distinguishing Vite SSR transform, Nitro inline, trace, and manifest, and cannot be masked with broad configuration. → See references/production-graph-and-runtime-closure.md
  10. A Turbo cache hit does not mean the runtime closure is trustworthy: only when diagnosing cache trustworthiness or when cache/artifact evidence conflicts, execute turbo run <task> --force; routine production acceptance does not execute this command, but must start the .output server and complete an HTTP smoke test. → See references/production-graph-and-runtime-closure.md
  11. nuxt-og-image also belongs to the Nuxt generation boundary: the conservative Nuxt 3 baseline must pin nuxt-og-image to 5.1.9；5.1.10+ may resolve Nuxt 4's @nuxt/kit/H3 v2. Pinning only h3: 1.15.11 is insufficient to constrain this transitive module; you must use package.json at the root pnpm.overrides, and use pnpm why nuxt-og-image @nuxt/kit h3 to recheck the actual tree. → See references/incident-repair.md
  12. Vercel READY does not equal runtime passing: after READY, you must request the deployed URL's pages and Content cache/search API, and read the Function runtime logs; without HTTP/log evidence you can only mark candidate or needs_check, and cannot write "production passed". → See references/production-graph-and-runtime-closure.md
  13. Protect the dirty tree before and after modifications: first record git status --short --untracked-files=all and the target diff; under time pressure it is forbidden to without authorization git add ., overwrite, reset, or mix the user's dirty changes into verification/commit. → See references/production-graph-and-runtime-closure.md
  14. Build tool overrides must be narrowed based on package and registry evidence：tsdown@0.3.1>rolldown is only used to reproduce rolldown@nightly registry resolution blockage; it is forbidden to use a root global rolldown override to mask peer/API incompatibility; you must first check pnpm why/list、manifest、lockfile and clean fresh install. → See references/production-graph-and-runtime-closure.md
  15. Dependency hoisting layer pollution (2026-09-05 ai-vue-doc evidence): in a monorepo, any package introducing a new transitive dependency (e.g., h3 v2) flips the pnpm hoisting layer, and all packages that "bare-import the dependency without declaring it" are affected at the same time;pnpm why shows a single version ≠ a single runtime instance. Fix with packageExtensions per-package injection; disable global override. → See references/dependency-triage.md
  16. optimizeDeps pre-bundling blind spot (2026-09-05 evidence)：.client plugin imports and packages dynamically imported inside plugins are not in the scan entry, and CJS transitive dependencies have no interop → the whole site does not hydrate and the console often shows no errors. Fix with vite.optimizeDeps.include explicitly included (nested > syntax). → See references/dependency-triage.md
  17. HTTP 200 ≠ content normal (catch-all illusion)：pages/[...slug].vue returns the 404 UI with 200; verification must assert <title> or the body content. → See references/ssr-hydration.md
  18. Module execution failure does not necessarily go through console (hydration diagnostic toolchain): determine hydration with __vue_app__; capture real errors with dynamic import(entry + '?v=diag'); locate the import chain with CDP Network.requestWillBeSent 's initiator.url; when automatic startup fails on Chrome 152, use the manual CDP fallback path. → See references/ssr-hydration.md
  19. Client/server component registration asymmetry (hoisted resolution trap): Vue hoists component resolution to the beginning of render,v-if is also executed when false; a component registered client-only that is referenced by SSR will necessarily warn, and fixing it with a static import will pull non-SSR-safe packages into the SSR graph causing 500; the standard solution is defineAsyncComponent. → See references/ssr-hydration.md
  20. Hardcoded self-reference remnants from renaming a forked package (2026-09-05 evidence): inside the fork's dist there may be hardcoded optimizeDeps.include entries with the old package name prefix, which vite will necessarily fail to resolve; use pnpm patch to fix the prefix (first confirm the dependency chain is physically complete). After introducing a fork, first grep its dist for self-reference strings. → See references/dependency-triage.md
  21. Isolation of non-SSR-safe packages and UI configuration traps: non-SSR-safe packages (top-level DOM APIs, CSS imports inside dist) must all go through the .client boundary; UI configuration (logo, etc.) changes must be accepted through a desktop-viewport browser; source-code v-if branch inference is unreliable. → See references/ssr-hydration.md
  22. Build-time platform binary warnings: verify before characterizing, and disable traceInclude：sharp binaries cannot be found does not necessarily mean a missing dependency — under nitro trace: false the traced directory is necessarily empty; first verify sharp loadability before characterizing.Do not configure traceInclude: ["sharp"]on any platform (falsified on real Vercel linux production: nft emitDependency throws a hard error on a resolved pseudo-path, failing the build). → See references/dependency-triage.md

Troubleshooting entry points (must be executed after a hit signal)

When a Content cache/search API 500、ERR_INVALID_URL、H3 sendError export is missing, entities/decode or @vueuse/core missing package,registerMessageResolver, Nitro prerender failure, page._id is empty, Windows builds with no output for a long time, or other signals appear,first read references/incident-repair.md, then modify the configuration or content.

When dependency-resolution-type signals appear —Failed to resolve dependency, a whole batch of packages simultaneously reporting a missing export of the same dependency, sharp binaries ... cannot be found, batch WARNs after a fork package upgrade,pnpm why contradicting actual behavior — first read references/dependency-triage.md。

SSR/hydration-type signals appear—the page returns 200 but all interactivity is dead, the console is clean yet hydration does not occur, Failed to resolve component: X, rendering a non-SSR-safe package during SSR causes a 500, dark mode/sidebar stops working and components are registered in the .client plugin—first read references/ssr-hydration.md。

When final Nitro OOM occurs, standalone MODULE_NOT_FOUND, the production graph is inflated by aliases or broad externalization, Turbo cache and .output are inconsistent, the artifact cannot start, or the HTTP smoke test fails,first read references/production-graph-and-runtime-closure.md。

Before modifying any nuxt.config.ts, manifest, or lockfile, first read the current working tree state; during deployment verification, you must distinguish four types of evidence: local, CI, Vercel, and browser.

During troubleshooting, you must first answer four things:

  1. Whether the actually installed shadcn-docs-nuxt、@ztl-uwu/nuxt-content、nuxt、h3、nuxt-og-image、@nuxt/kit belongs to the same compatibility generation; whether the version of .pnpm/node_modules in the hoisted layer and the resolution target of the bare import are consistent with pnpm why ;
  2. Whether the current error belongs to a Content/H3 runtime mismatch, a dependency hoisting layer/prebuild blind spot (→ dependency-triage.md), an SSR/hydration boundary (→ ssr-hydration.md), a Windows OOM/NFT build long tail, or the production graph's Vite SSR transform, Nitro inline, or trace/manifest closure;
  3. Whether the current configuration mistakenly uses legacy prerender:routes / routes.clear(), unconditional trace: false , or full inline；
  4. Whether the verification criteria include content assertions, hydration determination, browser desktop viewport screenshots, and an interaction loop (a 200 status code and a clean console are both insufficient as evidence).

Do not use a single homepage 200 or a successful local Windows build as a substitute for Content API, a fresh dependency tree, and Linux/Vercel verification.

Recommended reference repository priority

Learn from and extract configuration in the following order (from high to low):

  1. nuxt-umami-docs(a stable configuration paradigm for real projects)
  2. shadcn-docs-nuxt-starter(minimal skeleton)
  3. shadcn-docs-nuxt(framework source, used only to check default behavior)
  4. shadcn-docs-ui-thing(component library extension ideas, absorb with caution)

For each repository, prioritize reading these 6 files:package.json → nuxt.config.ts → app.config.ts → tailwind.config.* → assets/css/* → content/index.md

Standard implementation process

Step 1: Establish a minimal skeleton

docs-site/
├─ package.json
├─ nuxt.config.ts
├─ app.config.ts
├─ tailwind.config.js
├─ assets/css/
│  ├─ tailwind.css
│  └─ main.css
├─ content/
│  └─ index.md
├─ shims/                  ← 按需，仅当 debug 兼容问题出现时
│  └─ debug.ts
├─ components/content/     ← 按需，自定义 MDC 组件
└─ plugins/                ← 按需，注册 workspace 组件库

If you are refactoring an existing documentation site, first preserve the existing content/ hierarchy; do not mix it with "foundation rebuild" in a single change.

Step 2: Dependencies and scripts

See references/workspace.md § package.json baseline。

Core points:

  • Dependencies:nuxt、shadcn-docs-nuxt、vue、vue-router、tailwindcss、tailwindcss-animate
  • A Nuxt 3 documentation site must also pin nuxt-og-image: 5.1.9; if the theme's transitive dependencies declare a wider range, add package.json at the root pnpm.overrides.nuxt-og-image: 5.1.9
  • If you need to consume a workspace component library, add workspace:* dependencies
  • devDependencies：@iconify-json/lucide(required for Nuxt Icon)
  • The script must include predev / prebuild / postinstall all three places nuxt prepare
  • After a fresh install, you must check the actual resolved tree and commit the lockfile; do not let a transitive range such as ^2.13.9 determine the Content version

Step 3: Nuxt configuration

See references/nuxt-config.md。

First start with the minimal skeleton, and when client-side errors occur, patch compatibility item by item using the "patch on demand" strategy.

Step 4: Tailwind + CSS

See references/tailwind-css.md。

Hard checks：content scanning must cover node_modules/shadcn-docs-nuxt, otherwise theme classes are missing and dark styles behave abnormally.

Step 5: MDC content

See references/mdc-prettier.md。

Step 6: Verification

After execution, provide at least the following evidence:

Verification item Method
Startup pnpm --filter <pkg> dev → homepage HTTP 200
Dependencies pnpm list / pnpm why h3 → actual versions of core packages are explainable
Nuxt generation pnpm why nuxt-og-image @nuxt/kit h3 → nuxt-og-image@5.1.9 and no Nuxt 4/H3 v2 mixing occurs
Content fresh dev request cache/search API → HTTP 200 and index is non-empty
Build pnpm --filter <pkg> build → has .output artifacts
Production graph check alias, externalization, inline, trace, and the actual deployment package manifest at the first failing gate
Artifacts must start .output server → key pages and Content API HTTP smoke pass
Cache diagnostics only when diagnosing cache credibility or when cache/artifact evidence conflicts, execute turbo run <task> --force; routine production acceptance does not execute this command
Interaction dark mode toggle and sidebar collapse work
Content spot-check at least 1 ::demo-playground page, no bare marker text
console no error
Vercel runtime after READY, record the deployment URL, Function logs, page and Content API responses; do not mark complete without actual testing
Browser use a visible browser to walk the homepage/component demo user path, record console, hydration, and at least one interaction result; if no browser tool is available, explicitly mark as incomplete

Production closure hard gates (must be executed)

Proceed in the following order; do not skip or treat a later stage's green light as a fix for an earlier stage:

  1. Protect the write set: save a dirty-tree snapshot, confirm the target files and the boundaries of user changes.
  2. Lock the resolution tree: after fresh install, run pnpm why/list, verify the documentation package manifest, root trace entry, and lockfile.
  3. Locate the first-error stage: attribute the error to Vite SSR transform, Nitro Rollup, NFT trace, Function manifest, or runtime startup.
  4. Minimal change: prefer fixing the manifest/entry; only add a narrow noExternal、inline or alias when the exact error proves the stage requires it; by default do not add nitro.externals。
  5. Local artifacts: start .output/server/index.mjs, request pages and Content cache/search, record PID, response body, and logs.
  6. Remote closed loop: Linux/Vercel build, Function artifact, deployment URL, HTTP smoke, runtime logs, and visible browser evidence must each be recorded separately.
  7. Status criteria: if any external gate is missing, write candidate/needs_check; only after all runnable gates pass, write verified, and retain the deployment ID/SHA.

compatibilityDate must maintain the same object contract as the nitro-api-development skill: list both Cloudflare and Vercel platforms, their respective official documentation links, and fix it as 2024-09-19. It only represents the compatibility baseline of the target Nitro provider, not a fix for entities/decode or other runtime closures; do not degrade it to a single string or blindly copy a date from another project.

Documentation site runtime verified It is a separate chain from npm/plugin publishing; this skill does not treat the success of changeset, registry, tarball, or GitHub Release as the documentation site passing at runtime. When a task also requires publishing, establish an independent evidence chain according to the project publishing skill.

Common troubleshooting order

When interactions fail (dark mode toggle fails, sidebar buttons do not work),strictly follow this order：

  1. Firstcheck whether the browser console has module import errors → references/compat.md
  2. Thenfix dependency entry compatibility according to the first error (alias / optimizeDeps / dedupe / ssr.noExternal); Vite SSR transform, Nitro inline, and trace/manifest cannot substitute for each other. → references/production-graph-and-runtime-closure.md
  3. Finallyperform Tailwind / theme style checks → references/tailwind-css.md

When Content API returns 500, H3 export errors occur, or versions drift → references/incident-repair.md

final Nitro OOM、standalone MODULE_NOT_FOUND, artifact startup fails, or Turbo cache is untrustworthy → references/production-graph-and-runtime-closure.md

When the build hangs → references/windows.md

MDC raw text / hydration mismatch → references/mdc-prettier.md

Do-not-modify items (do not touch without clear evidence)

  1. extends: ["shadcn-docs-nuxt"](it is usually not the root cause)
  2. Content directory hierarchy (avoid coupling with content rearrangement during the foundation refactor phase)
  3. i18n multilingual approach (keep the minimal configuration for a single-language documentation site first)
  4. Major icon system overhaul (continue using the template's usable default solution first)
  5. ogImage: { enabled: false }(enabling it directly will trigger a 500)
  6. Production templates must not configure nitro.externalsby default; the Windows trace workaround can only be used as a local, rollback-capable diagnostic switch according to references/windows.md .
  7. Do not expand the registry resolution workaround for tsdown into a root global rolldown override。

Anti-pattern list

  1. Writing a large amount of "custom configuration" first, and only verifying whether it can start at the end.
  2. Using style changes to mask runtime import errors.
  3. Batch formatting content/**/*.md without doing page and console regression.
  4. Rearranging the content architecture and refactoring the foundation in the same round, making regressions impossible to localize.
  5. Reporting only that it "looks good" without attaching any reproducible verification evidence.
  6. Writing ::demo-playground as ## ::demo-playground。
  7. On Windows, directly judging "logs stopped" as "process hung" without first cleaning up old processes.
  8. Treating the historical prerender:routes clearing hook as the default configuration for all shadcn-docs-nuxt projects; you should first determine whether document-driven Content is used.
  9. Writing Vercel READY, a single page 200 , or local build results as production runtime passing.
  10. Overwriting configuration, executing git add . , or bringing user changes into release/verification without checking the dirty tree.
  11. Using a root global rolldown override to make pnpm install temporarily succeed, without verifying tsdown's peer/range/API compatibility.

Output requirements

When executing this skill, at minimum provide in the end:

  1. List of key changed files (configuration, styles, content)
  2. Run and build verification results
  3. If there are risk items, provide the next minimal remediation suggestion
  4. Clearly state whether the status is verified、candidate or needs_check, and list the unfinished provider/browser evidence gates