@nuxt/docs-nightly 4.3.0-29356103.2f7957ac → 4.3.0-29430576.f48ea4c8

package/3.guide/3.ai/1.mcp.md

@@ -0,0 +1,255 @@
+---
+title: Nuxt MCP Server
+description: Use Nuxt documentation in your AI assistants with Model Context Protocol support.
+navigation.title: MCP Server
+---
+
+## What is MCP?
+
+MCP (Model Context Protocol) is a standardized protocol that enables AI assistants to access external data sources and tools. Nuxt provides an MCP server that allows AI assistants like Claude Code, Cursor, and Windsurf to access documentation, blog posts, and deployment guides directly.
+
+The MCP server provides structured access to the Nuxt documentation, making it easy for AI tools to understand and assist with Nuxt development.
+
+## Resources
+
+The Nuxt MCP server provides the following resources for discovery:
+
+- **`resource://nuxt-com/documentation-pages`**: Browse all available documentation pages (defaults to v4.x)
+- **`resource://nuxt-com/blog-posts`**: Browse all Nuxt blog posts including releases and tutorials
+- **`resource://nuxt-com/deploy-providers`**: Browse all deployment providers and hosting platforms
+
+You're able to access these resources with tools like Claude Code by using `@`.
+
+## Tools
+
+The Nuxt MCP server provides the following tools organized by category:
+
+### Documentation
+
+- **`list_documentation_pages`**: Lists all available Nuxt documentation pages with their categories and basic information. Supports version filtering (3.x, 4.x, or all)
+- **`get_documentation_page`**: Retrieves documentation page content and details by path
+- **`get_getting_started_guide`**: Gets the getting started guide for a specific Nuxt version
+
+### Blog
+
+- **`list_blog_posts`**: Lists all Nuxt blog posts with metadata including dates, categories, and tags
+- **`get_blog_post`**: Retrieves blog post content and details by path
+
+### Deployment
+
+- **`list_deploy_providers`**: Lists all deployment providers and hosting platforms for Nuxt applications
+- **`get_deploy_provider`**: Retrieves deployment provider details and instructions by path
+
+## Prompts
+
+The Nuxt MCP server provides guided prompts for common workflows:
+
+- **`find_documentation_for_topic`**: Find the best Nuxt documentation for a specific topic or feature
+- **`deployment_guide`**: Get deployment instructions for a specific hosting provider
+- **`migration_help`**: Get help with migrating between Nuxt versions
+
+You're able to access these resources with tools like Claude Code by using `/`.
+
+## Setup
+
+The Nuxt MCP server uses HTTP transport and can be installed in different AI assistants.
+
+### ChatGPT
+
+::note{icon="i-lucide-info"}
+**Custom connectors using MCP are available on ChatGPT for Pro and Plus accounts** on the web.
+::
+
+Follow these steps to set up Nuxt as a connector within ChatGPT:
+
+1. **Enable Developer mode:**
+   - Go to Settings → Connectors → Advanced settings → Developer mode
+
+2. **Open ChatGPT settings**
+
+3. **In the Connectors tab, Create a new connector:**
+   - Give it a name: `Nuxt`
+   - MCP server URL: `https://nuxt.com/mcp`
+   - Authentication: `None`
+
+4. **Click Create**
+
+The Nuxt connector will appear in the composer's "Developer mode" tool later during conversations.
+
+### Claude Code
+
+::note{icon="i-lucide-info"}
+**Ensure Claude Code is installed** - Visit [Anthropic's documentation](https://docs.claude.com/en/docs/claude-code/quickstart) for installation instructions.
+::
+
+Add the server using the CLI command:
+
+```bash
+claude mcp add --transport http nuxt-remote https://nuxt.com/mcp
+```
+
+### Cursor
+
+Click the button below to install the Nuxt MCP server directly in Cursor:
+
+::u-button
+---
+to: "cursor://anysphere.cursor-deeplink/mcp/install?name=nuxt&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vbnV4dC5jb20vbWNwIn0%3D"
+label: Install MCP Server
+color: neutral
+icon: i-custom-cursor
+---
+::
+
+For manual setup, follow these steps:
+
+1. Open Cursor and go to "Settings" > "Tools & MCP"
+2. Add the Nuxt MCP server configuration
+
+Or manually create/update `.cursor/mcp.json` in your project root:
+
+```json [.cursor/mcp.json]
+{
+  "mcpServers": {
+    "nuxt": {
+      "type": "http",
+      "url": "https://nuxt.com/mcp"
+    }
+  }
+}
+```
+
+### Le Chat Mistral
+
+1. Navigate to "Intelligence" > "Connectors"
+2. Click on "Add Connector" button, then select "Custom MCP Connector"
+3. Create your Custom MCP Connector:
+    - Connector Name : `Nuxt`
+    - Connector Server : `https://nuxt.com/mcp`
+
+### Visual Studio Code
+
+::note{icon="i-lucide-info"}
+**Install required extensions** - Ensure you have [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) and [GitHub Copilot Chat](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat) extensions installed.
+::
+
+1. Open VS Code and access the Command Palette (Ctrl/Cmd + Shift + P)
+2. Type "Preferences: Open Workspace Settings (JSON)" and select it
+3. Navigate to your project's `.vscode` folder or create one if it doesn't exist
+4. Create or edit the `mcp.json` file with the following configuration:
+
+```json [.vscode/mcp.json]
+{
+  "servers": {
+    "nuxt": {
+      "type": "http",
+      "url": "https://nuxt.com/mcp"
+    }
+  }
+}
+```
+
+### GitHub Copilot Agent
+
+::note{icon="i-lucide-info"}
+**Repository administrator access required** to configure MCP servers for GitHub Copilot coding agent.
+::
+
+If you have already configured MCP servers in VS Code (replace the `servers` key with `mcpServers` for GitHub Copilot Agent), you can leverage a similar configuration for GitHub Copilot coding agent. You will need to add a `tools` key specifying which tools are available to Copilot.
+
+1. Navigate to your GitHub repository
+2. Go to **Settings** > **Code & automation** > **Copilot** > **Coding agent**
+3. In the **MCP configuration** section, add the following configuration:
+    ```json
+    {
+      "mcpServers": {
+        "nuxt": {
+          "type": "http",
+          "url": "https://nuxt.com/mcp",
+          "tools": ["*"]
+        }
+      }
+    }
+    ```
+4. Click **Save**
+
+#### Validating the Configuration
+
+To verify the MCP server is configured correctly:
+
+1. Create an issue in your repository and assign it to Copilot
+2. Wait for Copilot to create a pull request
+3. In the pull request, click **View session** in the "Copilot started work" timeline event
+4. Click the ellipsis button (**...**) at the top right, then click **Copilot** in the sidebar
+5. Expand the **Start MCP Servers** step to see the configured Nuxt tools
+
+For more information on using MCP with GitHub Copilot coding agent, see [Extend coding agent with MCP](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp).
+
+### Windsurf
+
+1. Open Windsurf and navigate to "Settings" > "Windsurf Settings" > "Cascade"
+2. Click the "Manage MCPs" button, then select the "View raw config" option
+3. Add the following configuration to your MCP settings:
+
+```json [.codeium/windsurf/mcp_config.json]
+{
+  "mcpServers": {
+    "nuxt": {
+      "type": "http",
+      "url": "https://nuxt.com/mcp"
+    }
+  }
+}
+```
+
+### Zed
+
+1. Open Zed and go to "Settings" > "Open Settings"
+2. Navigate to the JSON settings file
+3. Add the following context server configuration to your settings:
+
+```json [.config/zed/settings.json]
+{
+  "context_servers": {
+    "nuxt": {
+      "source": "custom",
+      "command": "npx",
+      "args": ["mcp-remote", "https://nuxt.com/mcp"],
+      "env": {}
+    }
+  }
+}
+```
+
+### Opencode
+
+1. In your project root, create `opencode.json`
+2. Add the following configuration:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "nuxt": {
+      "type": "remote",
+      "url": "https://nuxt.com/mcp",
+      "enabled": true
+    }
+  }
+}
+```
+
+## Prompts Examples
+
+Once configured, you can ask your AI assistant questions like:
+
+- "List all available Nuxt documentation pages"
+- "Get the introduction documentation"
+- "What's the difference between v3 and v4?"
+- "How do I deploy to Vercel?"
+- "Show me the latest blog posts"
+- "Help me migrate from Nuxt 3 to Nuxt 4"
+- "Search documentation about composables"
+- "Find deployment guides for Cloudflare"
+
+The AI assistant will use the MCP server to fetch structured JSON data and provide guided assistance for Nuxt development.

package/3.guide/3.ai/2.llms-txt.md

@@ -0,0 +1,65 @@
+---
+title: Nuxt LLMs.txt
+description: How to get AI tools like Cursor, Windsurf, GitHub Copilot, ChatGPT, and Claude to understand Nuxt concepts, APIs, and best practices.
+navigation.title: LLMs.txt
+---
+
+## What is LLMs.txt?
+
+LLMs.txt is a structured documentation format specifically designed for large language models (LLMs). Nuxt provides LLMs.txt files that contain comprehensive information about the framework, making it easy for AI tools to understand and assist with Nuxt development.
+
+These files are optimized for AI consumption and contain structured information about concepts, APIs, usage patterns, and best practices.
+
+## Available routes
+
+We provide LLMs.txt routes to help AI tools access our documentation:
+
+- **`/llms.txt`** - Contains a structured overview of all documentation pages and their links (~5K tokens)
+- **`/llms-full.txt`** - Provides comprehensive documentation including getting started guides, API references, blog posts, and deployment guides (~1M+ tokens)
+
+## Choosing the Right File
+
+::note{icon="i-lucide-info"}
+**Most users should start with `/llms.txt`** - it contains all essential information and works with standard LLM context windows.
+
+Use `/llms-full.txt` only if you need comprehensive implementation details and your AI tool supports large contexts (200K+ tokens).
+::
+
+## Important usage notes
+
+::warning{icon="i-lucide-alert-triangle"}
+**@-symbol must be typed manually** - When using tools like Cursor or Windsurf, the `@` symbol must be typed by hand in the chat interface. Copy-pasting breaks the tool's ability to recognize it as a context reference.
+::
+
+## Usage with AI Tools
+
+### Cursor
+
+Nuxt provides specialized LLMs.txt files that you can reference in Cursor for better AI assistance with Nuxt development.
+
+#### How to use
+
+1. **Direct reference**: Mention the LLMs.txt URLs when asking questions
+2. Add these specific URLs to your project context using `@docs`
+
+[Read more about Cursor Web and Docs Search](https://cursor.com/docs/context/symbols)
+
+### Windsurf
+
+Windsurf can directly access the Nuxt LLMs.txt files to understand framework usage and best practices.
+
+#### Using LLMs.txt with Windsurf
+
+- Use `@docs` to reference specific LLMs.txt URLs
+- Create persistent rules referencing these URLs in your workspace
+
+[Read more about Windsurf Web and Docs Search](https://docs.windsurf.com/windsurf/cascade/web-search)
+
+### Other AI Tools
+
+Any AI tool that supports LLMs.txt can use these routes to better understand Nuxt.
+
+#### Examples for ChatGPT, Claude, or other LLMs
+
+- "Using Nuxt documentation from https://nuxt.com/llms.txt"
+- "Follow complete Nuxt guidelines from https://nuxt.com/llms-full.txt"

package/3.guide/4.modules/.navigation.yml

@@ -0,0 +1,3 @@
+title: Module Author Guide
+titleTemplate: '%s · Nuxt Modules Author Guide'
+icon: i-lucide-box

package/3.guide/4.modules/1.getting-started.md

@@ -0,0 +1,103 @@
+---
+title: "Create Your First Module"
+description: "Learn how to create your first Nuxt module using the official starter template."
+---
+
+## Create a Module
+
+We recommend you get started with Nuxt modules using our [starter template](https://github.com/nuxt/starter/tree/module):
+
+::code-group{sync="pm"}
+
+```bash [npm]
+npm create nuxt -- -t module my-module
+```
+
+```bash [yarn]
+yarn create nuxt -t module my-module
+```
+
+```bash [pnpm]
+pnpm create nuxt -t module my-module
+```
+
+```bash [bun]
+bun create nuxt --template=module my-module
+```
+::
+
+This will create a `my-module` project with all the boilerplate necessary to develop and publish your module.
+
+**Next steps:**
+
+1. Open `my-module` in your IDE of choice
+2. Install dependencies using your favorite package manager
+3. Prepare local files for development using `npm run dev:prepare`
+4. Follow this document to learn more about Nuxt modules
+
+## Use the Starter Template
+
+Learn how to perform basic tasks with the module starter.
+
+::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/navigating-the-official-starter-template?friend=nuxt" target="_blank"}
+Watch Vue School video about Nuxt module starter template.
+::
+
+### Develop Your Module
+
+While your module source code lives inside the `src` directory, to develop a module you often need a Nuxt application to test it against. That's what the `playground` directory is for. It's a Nuxt application you can tinker with that is already configured to run with your module.
+
+You can interact with the playground like with any Nuxt application.
+
+- Launch its development server with `npm run dev`, it should reload itself as you make changes to your module in the `src` directory
+- Build it with `npm run dev:build`
+
+::note
+All other `nuxt` commands can be used against the `playground` directory (e.g. `nuxt <COMMAND> playground`). Feel free to declare additional `dev:*` scripts within your `package.json` referencing them for convenience.
+::
+
+### Run Tests
+
+The module starter comes with a basic test suite:
+
+- A linter powered by [ESLint](https://eslint.org), run it with `npm run lint`
+- A test runner powered by [Vitest](https://vitest.dev), run it with `npm run test` or `npm run test:watch`
+
+::tip
+Feel free to augment this default test strategy to better suit your needs.
+::
+
+### Build Your Module
+
+Nuxt modules come with their own builder provided by [`@nuxt/module-builder`](https://github.com/nuxt/module-builder#readme). This builder doesn't require any configuration on your end, supports TypeScript, and makes sure your assets are properly bundled to be distributed to other Nuxt applications.
+
+You can build your module by running `npm run prepack`.
+
+::tip
+While building your module can be useful in some cases, most of the time you won't need to build it on your own: the `playground` takes care of it while developing, and the release script also has you covered when publishing.
+::
+
+### Publish to npm
+
+::important
+Before publishing your module to npm, makes sure you have an [npmjs.com](https://www.npmjs.com) account and that you're authenticated to it locally with `npm login`.
+::
+
+While you can publish your module by bumping its version and using the `npm publish` command, the module starter comes with a release script that helps you make sure you publish a working version of your module to npm and more.
+
+To use the release script, first, commit all your changes (we recommend you follow [Conventional Commits](https://www.conventionalcommits.org) to also take advantage of automatic version bump and changelog update), then run the release script with `npm run release`.
+
+When running the release script, the following will happen:
+
+- First, it will run your test suite by:
+  - Running the linter (`npm run lint`)
+  - Running unit, integration, and e2e tests (`npm run test`)
+  - Building the module (`npm run prepack`)
+- Then, if your test suite went well, it will proceed to publish your module by:
+  - Bumping your module version and generating a changelog according to your Conventional Commits
+  - Publishing the module to npm (for that purpose, the module will be built again to ensure its updated version number is taken into account in the published artifact)
+  - Pushing a git tag representing the newly published version to your git remote origin
+
+::tip
+As with other scripts, feel free to fine-tune the default `release` script in your `package.json` to better suit your needs.
+::

package/3.guide/4.modules/2.module-anatomy.md

@@ -0,0 +1,138 @@
+---
+title: "Understand Module Structure"
+description: "Learn how Nuxt modules are structured and how to define them."
+---
+
+There are two types of Nuxt modules:
+
+- published modules are distributed on npm - you can see a list of some community modules on [the Nuxt website](/modules).
+- "local" modules exist within a Nuxt project, either [inlined in Nuxt config](/docs/4.x/api/nuxt-config#modules) or within [the `modules` directory](/docs/4.x/directory-structure/modules).
+
+In either case, they work in the same way.
+
+## Define Your Module
+
+::note
+When using the starter, your module definition is available at `src/module.ts`.
+::
+
+The module definition is the entry point of your module. It's what gets loaded by Nuxt when your module is referenced within a Nuxt configuration.
+
+At a low level, a Nuxt module definition is a simple, potentially asynchronous, function accepting inline user options and a `nuxt` object to interact with Nuxt.
+
+```ts
+export default function (inlineOptions, nuxt) {
+  // You can do whatever you like here..
+  console.log(inlineOptions.token) // `123`
+  console.log(nuxt.options.dev) // `true` or `false`
+  nuxt.hook('ready', (nuxt) => {
+    console.log('Nuxt is ready')
+  })
+}
+```
+
+You can get type hinting for this function using the higher-level `defineNuxtModule` helper provided by [Nuxt Kit](/docs/4.x/guide/going-further/kit).
+
+```ts
+import { defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule((options, nuxt) => {
+  nuxt.hook('pages:extend', (pages) => {
+    console.log(`Discovered ${pages.length} pages`)
+  })
+})
+```
+
+However, **we do not recommend** using this low-level function definition. Instead, to define a module, **we recommend** using the object-syntax with `meta` property to identify your module, especially when publishing to npm.
+
+This helper makes writing Nuxt modules more straightforward by implementing many common patterns needed by modules, guaranteeing future compatibility and improving the experience for both module authors and users.
+
+```ts
+import { defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  meta: {
+    // Usually the npm package name of your module
+    name: '@nuxtjs/example',
+    // The key in `nuxt.config` that holds your module options
+    configKey: 'sample',
+    // Compatibility constraints
+    compatibility: {
+      // Semver version of supported nuxt versions
+      nuxt: '>=3.0.0',
+    },
+  },
+  // Default configuration options for your module, can also be a function returning those
+  defaults: {},
+  // Shorthand sugar to register Nuxt hooks
+  hooks: {},
+  // Configuration for other modules - this does not ensure the module runs before
+  // your module, but it allows you to change the other module's configuration before it runs
+  moduleDependencies: {
+    'some-module': {
+      // You can specify a version constraint for the module. If the user has a different
+      // version installed, Nuxt will throw an error on startup.
+      version: '>=2',
+      // By default moduleDependencies will be added to the list of modules to be installed
+      // by Nuxt unless `optional` is set.
+      optional: true,
+      // Any configuration that should override `nuxt.options`.
+      overrides: {},
+      // Any configuration that should be set. It will override module defaults but
+      // will not override any configuration set in `nuxt.options`.
+      defaults: {},
+    },
+  },
+  // The function holding your module logic, it can be asynchronous
+  setup (moduleOptions, nuxt) {
+    // ...
+  },
+})
+```
+
+`defineNuxtModule` returns a wrapper function with the lower level `(inlineOptions, nuxt)` module signature. This wrapper function applies defaults and other necessary steps before calling your `setup` function:
+
+- Support `defaults` and `meta.configKey` for automatically merging module options
+- Type hints and automated type inference
+- Ensure module gets installed only once using a unique key computed from `meta.name` or `meta.configKey`
+- Automatically register Nuxt hooks
+- Automatically check for compatibility issues based on module meta
+- Expose `getOptions` and `getMeta` for internal usage of Nuxt
+- Ensuring backward and upward compatibility as long as the module is using `defineNuxtModule` from the latest version of `@nuxt/kit`
+- Integration with module builder tooling
+
+## Add Runtime Code
+
+::note
+When using the starter, the runtime directory is `src/runtime/`.
+::
+
+Modules, like everything in a Nuxt configuration, aren't included in your application runtime. However, you might want your module to provide, or inject runtime code to the application it's installed on. That's what the runtime directory enables you to do.
+
+Inside the runtime directory, you can provide any kind of assets related to the Nuxt app:
+- Vue components
+- Composables
+- [Nuxt plugins](/docs/4.x/directory-structure/app/plugins)
+
+To the [server engine](/docs/4.x/guide/concepts/server-engine), Nitro:
+- API routes
+- Middlewares
+- Nitro plugins
+
+Or any other kind of asset you want to inject in users' Nuxt applications:
+- Stylesheets
+- 3D models
+- Images
+- etc.
+
+You'll then be able to inject all those assets inside the application from your [module definition](#define-your-module).
+
+::tip
+Learn more about asset injection in [the recipes section](/docs/4.x/guide/modules/recipes-basics).
+::
+
+::warning
+Published modules cannot leverage auto-imports for assets within their runtime directory. Instead, they have to import them explicitly from `#imports` or alike.
+:br :br
+Auto-imports are not enabled for files within `node_modules` (the location where a published module will eventually live) for performance reasons.
+::