Contribution Guide

Learn how to contribute to the Nuxt DevTools.

Hi! We're really excited that you're interested in contributing to Nuxt DevTools! Before submitting your contribution, please read through the following guide.

Monorepo

The Nuxt DevTools repo is a monorepo using pnpm workspaces. The package manager used to install and link dependencies must be pnpm.

After cloning the repo, run in the root folder:

pnpm i
pnpm run build
Nuxt DevTools uses pnpm v12. If you are working on multiple projects with different versions of pnpm, it's recommended to enable Corepack by running corepack enable.

Packages

This repo contains the following packages:

  • @nuxt/devtools: the Nuxt DevTools module. Its client/ directory is the Nuxt app rendering the DevTools UI.
  • @nuxt/devtools-kit: the utility kit for module authors.
  • @nuxt/devtools-assets: the prebuilt client UI, served on demand.
  • @nuxt/devtools-onboard: the entry point Nuxt 5 ships, which loads Nuxt DevTools or offers to install it.
  • @nuxt/devtools-ui-kit: the UI components used by the client, deprecated for third-party integrations.

DevTools

Most of the scripts are forwarded to the root package.json. Run pnpm dev in the root folder to start the development server (Nuxt DevTools on top of its own client UI).

Or you can cd packages/devtools and run pnpm dev to start the development server.

The playgrounds under playgrounds/ use the published build by default. Set NUXT_DEVTOOLS_LOCAL=true to run them against the source code instead.

UI Kit

Normally when you are developing the Nuxt DevTools, the components in the UI Kit already get the HMR capabilities. But if you want to develop the UI Kit itself, you can run cd packages/devtools-ui-kit and run pnpm dev to start the playground for the UI Kit.

Checks

Before opening a pull request, run:

# ESLint, then the unit tests
pnpm test
# Type checks and unused code, after `pnpm build` or `pnpm dev:prepare`
pnpm typecheck
pnpm knip
# End-to-end tests, against the dev server and a built app
pnpm test:e2e:dev
pnpm test:e2e:built

Trying Local Changes

If you want to try your local changes in other Nuxt projects, you can use the local.ts module under the root folder. It runs the DevTools client from source in a dev server of its own.

For example, if you clone this repo to /users/me/nuxt-devtools, update your nuxt.config.ts:

nuxt.config.ts
export default defineNuxtConfig({
  modules: [
-   '@nuxt/devtools',
+   '/users/me/nuxt-devtools/local',
  ]
})

On the module side, the source TypeScript files are used directly, so you don't need to build every time. However, due to Node.js module caching, you need to restart your app to see the changes on the module side.

Documentation

The documentation lives in the docs/ directory and is published on nuxt.com/modules/devtools. Keep images next to the pages in docs/images/ and link them with a relative path, such as ![Overview tab](./images/overview.webp).

The DevTools screenshots are generated from the docs playground, a small shop with pages, components, server routes, a task and a storage mount. After a UI change, regenerate them with:

pnpm build
pnpm exec playwright install chromium
pnpm docs:screenshots

Each screenshot is a step in tests/docs-screenshots/screenshots.spec.ts: add one there to document a new tab. The docs-screenshots workflow, run from the Actions tab, does the same on CI and opens a pull request with the updated images.

To preview your changes, run the nuxt.com dev server with NUXT_DEVTOOLS_PATH set to your local clone of this repo. Pull requests changing docs/ can also be previewed on nuxt.com once a maintainer adds the preview:enabled label.