From 26cd8557e28f5b16aae58106e79ea0dbce104055 Mon Sep 17 00:00:00 2001 From: Amp Date: Wed, 28 Oct 2026 14:17:47 +0000 Subject: [PATCH 1/4] docs: move docs to nuxt.com/modules/devtools and update them for v4 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The docs are now flat pages in docs/, hosted by nuxt.com under /modules/devtools. The devtools.nuxt.com site (Nuxt Content app, landing page) is removed, and links across the repo, including the NDT_DEP diagnostics URLs, point to nuxt.com. The pages are updated for v4: features regrouped by the Nuxt group's sections with fresh v4 screenshots in docs/images/, Nuxt 5 onboarding, the module options, and the docks that moved to Vite DevTools and devframes plugins. pull-preview.yml (from nuxt/cli) comments nuxt.com previews on PRs changing docs/. Amp-Thread-ID: https://ampcode.com/threads/T-01a18296-d1f3-75e5-9fa1-f749b3e3f1fa Co-authored-by: SΓ©bastien Chopin --- .github/workflows/pull-preview.yml | 30 + CONTRIBUTING.md | 2 +- README.md | 10 +- docs/.env.example | 5 - docs/.gitignore | 12 - docs/.navigation.yml | 1 + docs/1.features.md | 199 + docs/2.composables.md | 48 + .../1.guide => }/3.upgrading-to-v4.md | 22 +- .../0.guide.md => 4.module-authors.md} | 27 +- .../1.utils-kit.md => 5.utils-kit.md} | 36 +- .../2.module/2.ui-kit.md => 6.ui-kit.md} | 24 +- ....migration-v4.md => 7.module-migration.md} | 19 +- docs/8.contributing.md | 81 + docs/README.md | 35 - docs/app/app.config.ts | 8 - docs/app/app.vue | 110 - docs/app/assets/css/main.css | 33 - docs/app/components/Illustration.vue | 191 - docs/app/components/Logo.vue | 30 - .../components/OgImage/OgImageDocs.takumi.vue | 39 - docs/app/layouts/default.vue | 3 - docs/app/layouts/docs.vue | 23 - docs/app/pages/[...slug].vue | 85 - docs/app/pages/index.vue | 313 - docs/app/pages/playground.vue | 22 - docs/content.config.ts | 47 - docs/content/1.guide/0.getting-started.md | 78 - docs/content/1.guide/1.features.md | 170 - docs/content/1.guide/2.composables.md | 31 - docs/content/3.development/0.contributing.md | 59 - docs/content/home/get-started.md | 13 - docs/content/index.yml | 53 - docs/images/components.webp | Bin 0 -> 67814 bytes docs/images/hooks.webp | Bin 0 -> 54326 bytes docs/images/imports.webp | Bin 0 -> 53226 bytes docs/images/modules.webp | Bin 0 -> 41840 bytes docs/images/overview.webp | Bin 0 -> 39136 bytes docs/images/pages.webp | Bin 0 -> 40632 bytes docs/index.md | 154 + docs/nuxt.config.ts | 52 - docs/package.json | 31 - docs/pnpm-lock.yaml | 13580 ---------------- docs/pnpm-workspace.yaml | 28 - docs/public/favicon.ico | Bin 4286 -> 0 bytes docs/public/images/components.webp | Bin 35898 -> 0 bytes docs/public/images/imports.webp | Bin 50712 -> 0 bytes docs/public/images/pages.webp | Bin 36602 -> 0 bytes docs/public/social-card.png | Bin 305692 -> 0 bytes docs/renovate.json | 3 - docs/server/api/search.json.get.ts | 3 - docs/server/tsconfig.json | 3 - docs/tsconfig.json | 3 - package.json | 2 - packages/devtools-assets/package.json | 2 +- packages/devtools-kit/package.json | 2 +- packages/devtools-kit/src/diagnostics.ts | 4 +- .../devtools-kit/test/diagnostics.test.ts | 4 +- packages/devtools-onboard/README.md | 4 +- packages/devtools-onboard/package.json | 2 +- packages/devtools-ui-kit/README.md | 2 +- packages/devtools-ui-kit/package.json | 4 +- .../client/pages/modules/overview.vue | 2 +- packages/devtools/package.json | 2 +- packages/devtools/test/code-server.test.ts | 2 +- .../client/components/ModuleAuthorNote.vue | 4 +- 66 files changed, 600 insertions(+), 15152 deletions(-) create mode 100644 .github/workflows/pull-preview.yml delete mode 100644 docs/.env.example delete mode 100644 docs/.gitignore create mode 100644 docs/.navigation.yml create mode 100644 docs/1.features.md create mode 100644 docs/2.composables.md rename docs/{content/1.guide => }/3.upgrading-to-v4.md (82%) rename docs/{content/2.module/0.guide.md => 4.module-authors.md} (79%) rename docs/{content/2.module/1.utils-kit.md => 5.utils-kit.md} (89%) rename docs/{content/2.module/2.ui-kit.md => 6.ui-kit.md} (62%) rename docs/{content/2.module/3.migration-v4.md => 7.module-migration.md} (93%) create mode 100644 docs/8.contributing.md delete mode 100644 docs/README.md delete mode 100644 docs/app/app.config.ts delete mode 100644 docs/app/app.vue delete mode 100644 docs/app/assets/css/main.css delete mode 100644 docs/app/components/Illustration.vue delete mode 100644 docs/app/components/Logo.vue delete mode 100644 docs/app/components/OgImage/OgImageDocs.takumi.vue delete mode 100644 docs/app/layouts/default.vue delete mode 100644 docs/app/layouts/docs.vue delete mode 100644 docs/app/pages/[...slug].vue delete mode 100644 docs/app/pages/index.vue delete mode 100644 docs/app/pages/playground.vue delete mode 100644 docs/content.config.ts delete mode 100644 docs/content/1.guide/0.getting-started.md delete mode 100644 docs/content/1.guide/1.features.md delete mode 100644 docs/content/1.guide/2.composables.md delete mode 100644 docs/content/3.development/0.contributing.md delete mode 100644 docs/content/home/get-started.md delete mode 100644 docs/content/index.yml create mode 100644 docs/images/components.webp create mode 100644 docs/images/hooks.webp create mode 100644 docs/images/imports.webp create mode 100644 docs/images/modules.webp create mode 100644 docs/images/overview.webp create mode 100644 docs/images/pages.webp create mode 100644 docs/index.md delete mode 100644 docs/nuxt.config.ts delete mode 100644 docs/package.json delete mode 100644 docs/pnpm-lock.yaml delete mode 100644 docs/pnpm-workspace.yaml delete mode 100644 docs/public/favicon.ico delete mode 100644 docs/public/images/components.webp delete mode 100644 docs/public/images/imports.webp delete mode 100644 docs/public/images/pages.webp delete mode 100644 docs/public/social-card.png delete mode 100644 docs/renovate.json delete mode 100644 docs/server/api/search.json.get.ts delete mode 100644 docs/server/tsconfig.json delete mode 100644 docs/tsconfig.json diff --git a/.github/workflows/pull-preview.yml b/.github/workflows/pull-preview.yml new file mode 100644 index 0000000000..fbab30ed0a --- /dev/null +++ b/.github/workflows/pull-preview.yml @@ -0,0 +1,30 @@ +name: pull-preview + +on: + # zizmor: ignore[dangerous-triggers] - DO NOT add actions/checkout: the called workflow only reads PR metadata + pull_request_target: + branches: + - main + paths: + - 'docs/**' + types: + - opened + - reopened + - synchronize + - labeled + - unlabeled + - closed + +permissions: {} + +concurrency: + group: pull-preview-${{ github.event.pull_request.number }} + cancel-in-progress: false + queue: max + +jobs: + comment: + if: github.repository == 'nuxt/devtools' + permissions: + pull-requests: write + uses: nuxt/nuxt.com/.github/workflows/pull-preview-comment.yml@main # zizmor: ignore[unpinned-uses] - nuxt.com owns the preview comment diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7b6d036400..06c7134d15 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1 +1 @@ -Please refer to the [Contribution Guide](https://devtools.nuxt.com/development/contributing) in our documentation. +Please refer to the [Contribution Guide](https://nuxt.com/modules/devtools/contributing) in our documentation. diff --git a/README.md b/README.md index 18d7e262d2..b3c27019a1 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -Nuxt DevTools +Nuxt DevTools

@@ -20,7 +20,7 @@ Unleash Nuxt Developer Experience. πŸ‘‹ Introduction | πŸ’‘ Ideas & Suggestions | πŸ—ΊοΈ Project Roadmap | - πŸ“š Documentation + πŸ“š Documentation

> [!NOTE] @@ -46,7 +46,7 @@ export default defineNuxtConfig({ ### Nuxt 4 -Nuxt 5 ships with Nuxt DevTools v4. Nuxt 4.5+ still bundles v3; override `@nuxt/devtools` to `^4.0.0` with your package manager (`overrides` for npm and pnpm, `resolutions` for yarn), remove your lockfile and reinstall. See the [upgrade guide](https://devtools.nuxt.com/guide/upgrading-to-v4) for details and for what changed. +Nuxt 5 ships with Nuxt DevTools v4. Nuxt 4.5+ still bundles v3; override `@nuxt/devtools` to `^4.0.0` with your package manager (`overrides` for npm and pnpm, `resolutions` for yarn), remove your lockfile and reinstall. See the [upgrade guide](https://nuxt.com/modules/devtools/upgrading-to-v4) for details and for what changed. ### Nightly Release Channel @@ -122,11 +122,11 @@ Read the [**Announcement Blog Post 🎊**](https://nuxt.com/blog/nuxt-devtools-v ## Module Authors -Please refer to the [Module Authors Guide](https://devtools.nuxt.com/module/guide). +Please refer to the [Module Authors Guide](https://nuxt.com/modules/devtools/module-authors). ## Contribution Guide -Please refer to the [Contribution Guide](https://devtools.nuxt.com/development/contributing). +Please refer to the [Contribution Guide](https://nuxt.com/modules/devtools/contributing). ## Anonymous Usage Analytics diff --git a/docs/.env.example b/docs/.env.example deleted file mode 100644 index d8e52d7b0f..0000000000 --- a/docs/.env.example +++ /dev/null @@ -1,5 +0,0 @@ -# To use Nuxt UI Pro in production -NUXT_UI_PRO_LICENSE= - -# Used when pre-rendering the docs for dynamic OG images -NUXT_PUBLIC_SITE_URL= diff --git a/docs/.gitignore b/docs/.gitignore deleted file mode 100644 index 69f6b69d07..0000000000 --- a/docs/.gitignore +++ /dev/null @@ -1,12 +0,0 @@ -node_modules -*.iml -.idea -*.log* -.nuxt -.vscode -.DS_Store -coverage -dist -sw.* -.env -.output diff --git a/docs/.navigation.yml b/docs/.navigation.yml new file mode 100644 index 0000000000..7234c8d68c --- /dev/null +++ b/docs/.navigation.yml @@ -0,0 +1 @@ +title: Nuxt DevTools diff --git a/docs/1.features.md b/docs/1.features.md new file mode 100644 index 0000000000..90c9942480 --- /dev/null +++ b/docs/1.features.md @@ -0,0 +1,199 @@ +--- +title: Features +description: 'Discover everything Nuxt DevTools shows you about your Nuxt app.' +--- + +Nuxt DevTools registers a `Nuxt` group in the [Vite DevTools](https://github.com/vitejs/devtools) panel. Its tabs are sorted into sections: **App**, **Analyze**, **Server**, **Modules** and **Advanced**. Some tabs only appear when they have something to show, for example Server Tasks when your project defines tasks. + +Next to the `Nuxt` group, the panel also holds docks shared with every Vite tool: [Vue DevTools](#vue-devtools), [Inspect](#inspect), [Terminals](#terminals) and [Messages](#messages). + +## App + +### Overview + +Shows a quick overview of your app: the Nuxt and Vue versions (with a hint when an update is available), how many pages, components, imports, modules and plugins you use, and how long your app took to load. + +![Overview tab](./images/overview.webp) + +### Pages + +Shows your current routes with their layout and middleware, and provides a quick way to navigate between pages. Edit the current path to see how each route is matched. + +![Pages tab](./images/pages.webp) + +### Components + +Shows all the components in your app and where they come from. Search for them and jump to their source code. + +![Components tab](./images/components.webp) + +The Graph view shows the relationships between components and the dependencies of each one. Its dependency edges need the optional [`vite-plugin-inspect`](#inspect) installed. + +You can also inspect your app's DOM tree to find which component renders it. Turn the inspector off with `devtools.componentInspector: false`. + +### Imports + +Shows all the auto-imports registered to Nuxt, which files use them, and where they come from. Some entries provide short descriptions and documentation links. + +![Imports tab](./images/imports.webp) + +### Modules + +Shows the modules you have installed with their repository, documentation, version and setup time. You can install or remove any Nuxt module from the [module registry](/modules) with one click. + +![Modules tab](./images/modules.webp) + +### Error + +Appears while the current page holds an error, and shows it with its stack trace. + +## Analyze + +### Payload + +Shows the state and data payloads of your page: keyed state from `useState()` and the data fetched with `useAsyncData()` and `useFetch()`, which you can re-fetch. + +### Runtime Configs + +Shows your App Config and runtime config. App Config and public runtime config can be edited live; private runtime config is read-only, as it is never exposed to the client. + +### Plugins + +Shows the plugins of your app, with their mode (client or server) and initialization time. + +### Timeline + +Records when auto-imported composables run and when the route changes, to help you understand the order in which things happen. It is opt-in: until it is enabled, the tab offers to enable it for you, which updates your `nuxt.config` and restarts Nuxt. + +```ts [nuxt.config.ts] +export default defineNuxtConfig({ + devtools: { + timeline: { + enabled: true, + }, + }, +}) +``` + +By default it tracks the composables from `#app`, `@unhead/vue` and your `composables/` directory. Use `timeline.functions.include`, `includeFrom` and `exclude` to change what is tracked. + +### Build Analyze + +Runs an analyze build and shows the bundle size of your project. Reports are saved so you can compare the bundle size of different builds. The build output streams to the [Terminals](#terminals) dock. + +### Assets + +The Assets panel, powered by [`@devframes/plugin-assets`](https://npmx.dev/package/@devframes/plugin-assets), lists the files of your `public/` directory. Preview, upload, rename and delete them from the panel. Limit which files can be uploaded with `devtools.assets.uploadExtensions`, or set it to `'*'` to accept any. + +### Open Graph + +The Open Graph panel, powered by [`@devframes/plugin-og`](https://npmx.dev/package/@devframes/plugin-og), fetches a page from your dev server, shows its Open Graph and Twitter metadata, and previews its social card on X (Twitter), Facebook, LinkedIn and Telegram. + +## Server + +### Server Routes + +Shows all the [Nitro](https://nitro.build) routes of your project, with a playground to send requests to your endpoints and inspect their responses. + +### Server Tasks + +Appears when Nitro's `experimental.tasks` is enabled and your project defines [tasks](https://nitro.build/guide/tasks). Pass task payloads, run them, and see their results. + +### Storage + +Shows the [Nitro storage](https://nitro.build/guide/storage) mounts of your project. You can create, edit, and delete their items. + +## Modules + +Tabs contributed by the Nuxt modules you install (for example `@nuxt/fonts`, `@nuxt/scripts` or `nuxt-og-image`) appear in this section. See the [Module Authors Guide](/modules/devtools/module-authors) to add your own. + +### Code Server + +Embeds [Coder's `code-server`](https://coder.com/docs/code-server/install). It is enabled by default: Nuxt DevTools detects the local `code-server` binary during setup, but starts no process until you choose **Launch editor**. If the binary is missing, the tab shows installation instructions instead. + +When launched, Code Server opens the Nuxt root directory by default, hands the generated authenticated session to the iframe, and streams process output to the [Terminals](#terminals) dock. The process is also stopped when Nuxt closes. + +```ts [nuxt.config.ts] +export default defineNuxtConfig({ + devtools: { + codeServer: { + enabled: true, + // All fields below are optional. + bin: '/usr/local/bin/code-server', + cwd: '/workspace/my-app', + serverPort: 8080, + host: '127.0.0.1', + args: ['--disable-file-downloads'], + env: { LOG_LEVEL: 'info' }, + cookieSuffix: 'my-app', + startTimeout: 30_000, + }, + }, +}) +``` + +The options are `enabled`, `bin`, `cwd`, `serverPort`, `host`, `args`, `env`, `cookieSuffix`, and `startTimeout`. When omitted, the upstream plugin defaults apply: the `code-server` binary, loopback host, a free port near Code Server's port 8080, and a 30-second startup timeout. Nuxt changes only the default `cwd`, setting it to the Nuxt root. Set `codeServer.enabled: false` to remove the tab. + +Nuxt DevTools owns authentication, so `args` cannot override `--auth`, `--bind-addr`, or `--cookie-suffix`, and `env` cannot set `PASSWORD` or `HASHED_PASSWORD`. Configure the bind host and cookie suffix through their dedicated fields. + +The editor iframe connects directly to the Code Server port; Nuxt does not proxy it through `app.baseURL`. The browser must be able to reach that host and port, and an HTTPS page cannot embed an HTTP-only editor because of browser mixed-content rules. Binding to a non-loopback interface also exposes the port to that network, so apply the usual network controls. + +This integration uses the experimental upstream `@devframes/plugin-code-server`. HTTPS, reverse proxies, containers, and remote port forwarding are governed by that plugin and your environment; Nuxt does not extend them. + +## Advanced + +### Hooks + +Shows the time spent in each Nuxt hook on the client and the server, to help you find performance bottlenecks. + +![Hooks tab](./images/hooks.webp) + +### Virtual Files + +Shows the virtual files Nuxt generates to support its conventions. + +### Debug + +With `debug: true` in your `nuxt.config`, lists which module changed which Nuxt option during setup. + +### Data Inspector + +An interactive [jora](https://discoveryjs.github.io/jora/) query workbench over your live server-side configuration. It replaces the read-only Nuxt Options Viewer of v3. Turn it off with `devtools.dataInspector: false`. + +Its `Nuxt Application` source exposes three root fields: + +- `nuxt` β€” the resolved Nuxt options. +- `nitro` β€” the resolved Nitro options, once Nitro is created. +- `vite` β€” the live Vite dev server: its resolved config at `vite.config`, and its `environments` (`client` and `ssr`). + +The source is live: every query reads the current state, so re-running a query after the Nitro and Vite hooks have completed reflects the latest values. Six presets are provided: **Overview**, **Nuxt modules**, **Vite plugins**, **Vite config**, **Vite environments** and **Nitro routes**, each leaving functions out so browsing configuration does not foreground methods. + +Module authors who want to expose their own data can install [`@devframes/plugin-data-inspector`](https://npmx.dev/package/@devframes/plugin-data-inspector) and register sources through its `registerDataSource` API; they appear in the same inspector without any Nuxt-specific wrapper. + +::warning +The `getServerData` DevTools RPC that backed the old viewer is deprecated (`NDT_DEP_0009`). It still works as a compatibility shim but will be removed in v5; use the Data Inspector instead. +:: + +### Settings + +Change the UI scale, toggle the help buttons, choose the editor used by _Open in editor_, opt out of anonymous telemetry, or reset the local DevTools state. Hiding, pinning and reordering tabs is handled by Vite DevTools. + +## Vite DevTools Docks + +### Vue DevTools + +Nuxt installs [Vue DevTools](https://devtools.vuejs.org) (`vite-plugin-vue-devtools`), which registers its own dock next to the `Nuxt` group to inspect your components' state, Pinia stores and more. Turn it off with `devtools.vueDevTools: false`. + +### Inspect + +Exposes the [`vite-plugin-inspect`](https://github.com/antfu/vite-plugin-inspect) integration as its own dock, to inspect the transformation steps of Vite. + +`vite-plugin-inspect` is an optional peer dependency, so it is not installed by default. Until you add it to your project, the Inspect dock shows an install launcher: click it to install the plugin and restart the dev server. Set `devtools.viteInspect: false` to remove the dock and its launcher. + +### Terminals + +Processes started by DevTools and modules, such as module installs, Build Analyze and Code Server, appear in the shared Terminals dock of Vite DevTools. + +### Messages + +Notifications from DevTools and modules land in the Messages dock of Vite DevTools as a persistent list, optionally also shown as a toast. diff --git a/docs/2.composables.md b/docs/2.composables.md new file mode 100644 index 0000000000..2a75c1c228 --- /dev/null +++ b/docs/2.composables.md @@ -0,0 +1,48 @@ +--- +title: Composables +description: 'Open or control Nuxt DevTools from your app with the useNuxtDevTools composable.' +--- + +To open or control Nuxt DevTools from your application in development, use the auto-imported `useNuxtDevTools()` composable. + +```vue + + + +``` + +In ` - - diff --git a/docs/app/assets/css/main.css b/docs/app/assets/css/main.css deleted file mode 100644 index 038e61a0ac..0000000000 --- a/docs/app/assets/css/main.css +++ /dev/null @@ -1,33 +0,0 @@ -@import 'tailwindcss'; -@import '@nuxt/ui-pro'; - -@theme { - --color-slate-50: #f8fafc; - --color-slate-100: #f1f5f9; - --color-slate-200: #e2e8f0; - --color-slate-300: #cbd5e1; - --color-slate-400: #94a3b8; - --color-slate-500: #64748b; - --color-slate-600: #475569; - --color-slate-700: #334155; - --color-slate-800: #1e293b; - --color-slate-900: #0f172a; - --color-slate-950: #020420; - - --color-green-50: #effdf5; - --color-green-100: #d9fbe8; - --color-green-200: #b3f5d1; - --color-green-300: #75edae; - --color-green-400: #00dc82; - --color-green-500: #00c16a; - --color-green-600: #00a155; - --color-green-700: #007f45; - --color-green-800: #016538; - --color-green-900: #0a5331; - --color-green-950: #052e16; - - --font-sans: - 'Inter var', 'Inter', ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, - 'Helvetica Neue', Arial, 'Noto Sans', sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', - 'Noto Color Emoji'; -} diff --git a/docs/app/components/Illustration.vue b/docs/app/components/Illustration.vue deleted file mode 100644 index 62827ac44d..0000000000 --- a/docs/app/components/Illustration.vue +++ /dev/null @@ -1,191 +0,0 @@ - diff --git a/docs/app/components/Logo.vue b/docs/app/components/Logo.vue deleted file mode 100644 index b1f358abdf..0000000000 --- a/docs/app/components/Logo.vue +++ /dev/null @@ -1,30 +0,0 @@ - diff --git a/docs/app/components/OgImage/OgImageDocs.takumi.vue b/docs/app/components/OgImage/OgImageDocs.takumi.vue deleted file mode 100644 index 07a0d960f9..0000000000 --- a/docs/app/components/OgImage/OgImageDocs.takumi.vue +++ /dev/null @@ -1,39 +0,0 @@ - - - diff --git a/docs/app/layouts/default.vue b/docs/app/layouts/default.vue deleted file mode 100644 index ba4672f56d..0000000000 --- a/docs/app/layouts/default.vue +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/docs/app/layouts/docs.vue b/docs/app/layouts/docs.vue deleted file mode 100644 index 1bfd3588ec..0000000000 --- a/docs/app/layouts/docs.vue +++ /dev/null @@ -1,23 +0,0 @@ - - - diff --git a/docs/app/pages/[...slug].vue b/docs/app/pages/[...slug].vue deleted file mode 100644 index 9137c9bdba..0000000000 --- a/docs/app/pages/[...slug].vue +++ /dev/null @@ -1,85 +0,0 @@ - - - diff --git a/docs/app/pages/index.vue b/docs/app/pages/index.vue deleted file mode 100644 index 334100155f..0000000000 --- a/docs/app/pages/index.vue +++ /dev/null @@ -1,313 +0,0 @@ - - -