Nuxt

Understanding Nuxt.js vs. Vue.js

Nuxt.jsis an open-source framework built on top of Vue.js. While Vue.js is a library focused on the view layer (the UI), Nuxt is a "meta-framework" that provides the architecture, directory structure, and configurations needed to build production-ready applications.

Think of it this way: Vue provides the engine, while Nuxt provides the entire car.

Key Differences at a Glance

The following table highlights the architectural and functional shifts between the two:

Core Enhancements in Nuxt.js

1. Rendering Modes: Nuxt allows you to choose how your app is delivered. It supports Rendering (SSR), which sends fully rendered HTML to the browser, and Site Generation (SSG), which pre-builds the site at deployment.
2. Automatic Routing: You don't need to write a router file. If you create a file named about.vue in the pages/ directory, Nuxt automatically creates the /about route for you.
3. SEO & Meta Tags: Nuxt provides built-in components and composables (like useHead) to easily manage meta titles, descriptions, and scripts for individual pages, making it superior for search engine visibility.
4. Auto-imports: Nuxt automatically imports components, composables, and Vue APIs, reducing boilerplate code and keeping your script tags clean.
5. Nitro Engine: Nuxt uses the Nitro server engine, allowing you to write API routes (server-side code) directly within the same project.

In the context of Nuxt, "Convention over Configuration" is a design philosophy that minimizes the number of decisions a developer needs to make. Instead of manually configuring every aspect of the application (as you would in a raw Vue.js setup), Nuxt assumes "sensible defaults" based on how you name and place your files.

If you follow the established conventions (the folder structure), Nuxt handles the configuration (the underlying code) automatically.

How Convention Replaces Configuration

The following table compares the manual effort required in a standard Vue project versus the automated "convention" approach in Nuxt:

Key Benefits of This Approach

• Faster Development (Speed to Market): You spend less time writing "glue code" (boilerplate) and more time writing feature logic.
• Standardization: Because the structure is opinionated, any Nuxt developer can jump into a project and immediately know where the routes, stores, and components are located.
• Reduced Decision Fatigue: You don't have to argue over where to put files or how to name them; the framework has already decided the most efficient way.
• Built-in Optimization: Because Nuxt knows your structure, it can automatically perform code-splitting—only loading the JavaScript necessary for the specific page the user is visiting.

Rendering Modes Comparison

Nuxt 3 is unique because it allows you to mix and match different rendering strategies within a single application using Hybrid Rendering. By default, it uses Universal Rendering, but you can configure specific routes to behave differently.

Rendering Modes Comparison

The table below breaks down the primary ways Nuxt handles content delivery:

Universal Rendering (Default):

• The server generates the HTML and sends it to the browser.
• Once the browser receives the HTML, it "hydrates" it (downloads JS to make it interactive).
• Pros:Excellent SEO and fast "First Contentful Paint."
Client-Side Rendering (CSR):
• You can disable SSR by setting ssr: false in nuxt.config.ts
• The browser receives a nearly empty HTML file and builds the UI using JavaScript.
• Pros: Ideal for highly interactive apps where SEO is not a priority (e.g., an admin panel).
Hybrid Rendering:

This allows you to define Route Rules in your config file. For example, you can make your homepage static but keep your search results dynamic.

To start a new Nuxt 3 project, you use nuxi, the Nuxt Command Line Interface. It is designed to be lightweight and handles the scaffolding of the project structure automatically.

Quick Start Command

Run the following command in your terminal to initialize a project:

Step-by-Step Installation Process

Key Prerequisites

• Node.js: Ensure you have version 18.10.0 or newer installed.
• Text Editor: Visual Studio Code is recommended, specifically with the Volar extension (configured for Vue 3).
• Browser: Any modern evergreen browser (Chrome, Firefox, Edge, Safari).

What Happens Behind the Scenes?

When you run the init command, Nuxt:

1. Clones a minimalstarter template.
2. Sets up the directory structure(e.g., .nuxt, server, public).
3. Pre-configures TypeScriptsupport by default.
4. Prepares the Nitro serverengine for development.

The nuxt.config.ts file is the central configuration hub for a Nuxt 3 application. It allows you to override the default "Convention over Configuration" settings, register modules, and define global behaviors for both the client and the server.Because it is written in TypeScript, it provides full IntelliSense (autocompletion) to help you discover available options as you type

Core Responsibilities of nuxt.config.ts

Key Features and Structure

• defineNuxtConfig Wrapper:This helper function ensures your configuration is type-checked.
• Runtime Config: Nuxt distinguishes between public keys (accessible in the browser) and private keys (accessible only by the Nitro server), preventing sensitive data leaks.
• Auto-updates: In development mode, Nuxt watches this file; most changes will trigger an automatic restart of the development server to apply the new settings.

Code Example: A Typical Config

In Nuxt, the In Nuxt, the means your application's URL structure is defined by the physical files and folders within the pages/ directory. Nuxt uses the Nitro engine to scan this directory and automatically generate a router configuration using vue-router under the hood.

This removes the need to manually maintain a router.js file.

Mapping Files to URLs

The naming convention of your files directly determines the path. Here is how common routing patterns are translated:

Key Routing Concepts

• Dynamic Routes([id].vue): Use square brackets to define a parameter. You can access this in your component using useRoute().params.id.
• Catch-all Routes ([...slug].vue): The ellipsis allows the route to match multiple path segments (e.g., /blog/2026/02/news).
• Nested Routes: If you create a folder and a.vue file with the same name (e.g., parent.vue and parent/child.vue) , Nuxt will treat the child as a nested view inside a component within the parent.
• Navigation: Instead of standard a tags, Nuxt provides the component. This enables smart pre-fetching (loading the next page's data before the user even clicks) and faster client-side transitions.
• Mount Service: Handles SD cards and internal storage mounting.
• Telephony Registry: Monitors signal strength and call status.

Validation and Middleware

You can also add a definePageMeta macro inside your page files to:

• Add Middleware (e.g., checking if a user is logged in before showing the page).
• Set a specific Layout
• Validate route parameters (e.g., ensuring an ID is a number).

The .nuxt directory is the generated output of the Nuxt development environment. It serves as the "brain" of your project while it is running in development mode or being prepared for production.

You should generally never manually edit files inside this folder, as they are overwritten every time you run npm run dev or npm run build.

Key Functions of the .nuxt Directory

Crucial Facts for Developers

• Git Ignore:This directory is automatically added to your .gitignore. You should not commit it to version control because its contents are specific to the local machine and the current build.
• Virtual File System: Nuxt uses a virtual file system (VFS) to bridge the gap between your source code and the running application. The .nuxt folder is the physical manifestation of that VFS.
• Troubleshooting: If you encounter strange "module not found" errors or TypeScript mismatches, a common fix is to delete the .nuxt folder and restart your development server. This forces Nuxt to regenerate everything from scratch.
• Types Generation: You can manually trigger the generation of these files (specifically for IDE support) by running:

In Nuxt, dynamic routes are created using square bracket syntax [] within your file or folder names in the pages/ directory. This tells Nuxt that the segment of the URL is a variable (parameter) rather than a static string.

Creating the File Structure

To create a route like /user/123, you would structure your directory as follows:

• File Path: pages/user/[id].vue
• Resulting URL: /user/:id (where :id can be anything like 123, abc or john-doe).

Accessing the Route Parameter

Once the file is created, you need to extract the id to use it in your logic (e.g., fetching user data from an API). You do this using the useRoute() composable.

Advanced Dynamic Routing Patterns

Nuxt supports more complex scenarios beyond simple IDs:

• Multiple Parameters: pages/posts/[category]/[id].vue maps to /posts/tech/123
• Catch-all Routes: pages/docs/[...slug].vue maps to /docs/intro.
• Optional Parameters: pages/user/[[id]].vue (double brackets) makes the id optional, meaning it matches both /user and /user/123.

Parameter Validation

You can use the definePageMeta macro to ensure the dynamic parameter meets specific criteria (e.g., ensuring an ID is a number). If validation fails, Nuxt will automatically return a 404 error.

While both directories contain .vue files, they serve distinct architectural purposes in a Nuxt application. The primary difference lies in routing and lifecycle.

Core Differences

The following table summarizes the structural and functional divergence between the two:

Detailed Roles

The pages/ Directory Directory

• Entry Points: Every file here is an entry point for a user.
• Orchestration: Pages act as "containers." They fetch data (using useFetch or useAsyncData) and then pass that data down to various components.
• Layouts & Middleware: This is where you define which layout a page uses or which middleware should run before the user views the content.

The components/ components/

• Modularity: This is for "bricks" like AppButton.vue, TheNavbar.vue, or UserProfileCard.vue.
• Organized Subfolders: If you have components/base/Button.vue, Nuxt allows you to use it as automatically.
• Lazy Loading: You can prefix a component with Lazy (e.g., ) to delay downloading its code until it’s actually needed on the screen.

Visualizing the Relationship

• A Page is a specific destination (The "Profile" Page).
• A Component is a piece of that destination (The "Avatar" image or the "Follow" button).

Nuxt features a powerful Auto-import system that eliminates the need to manually write import statements for your internal files or the Vue/Nuxt APIs.

How Auto-imports Work

Nuxt scans specific directories during the development process and generates a Virtual File System (stored in .nuxt/imports.d.ts) ) that makes these functions and components globally available to your project.

Specific Rules for Components

• Nested Folders: If you have components/base/Button.vue , the component name is derived from the path: .
• Lazy Loading: You can skip the initial JavaScript bundle for a component by prefixing it with Lazy. For example, using will only download the component's code when the modal is actually rendered.
• Direct Imports: If you prefer manual imports (e.g., for complex IDE refactoring), you can still import them normally; Nuxt will not conflict with manual imports.

Specific Rules for Composables

• Top-level only Nuxt only scans the top-level files in the composables/ directory (e.g., composables/useAuth.ts).
• Nested Composables: If you want to organize composables in subfolders, you must either export them from an index.ts in the root of the folder or configure the nuxt.config.ts to scan those subfolders.

Developer Experience (IDE Support)

s Because Nuxt generates TypeScript declaration files in the .nuxt folder, your IDE (like VS Code with Volar) will still provide:

• Autocompletion: Suggestions as you type the component or function name.
• Type Checking:Warnings if you pass the wrong props to an auto-imported component.
• Go to Definition: Clicking the component name will still take you to the source file.s

Universal Rendering (SSR) in Nuxt

Universal Rendering (also known as Server-Side Rendering or SSR) is a technique where the server executes the JavaScript code and generates the full HTML of a page before sending it to the browser.

Once the browser receives the HTML, it displays it immediately. It then downloads the JavaScript to "hydrate" the page, making it interactive (connecting event listeners, state, etc.).

Universal Rendering vs. Client-Side Rendering

Why is it the Default?

Nuxt chooses Universal Rendering as the default because it provides the best balance of user experience and technical performance for modern web applications.

• Optimized SEO: Since the server sends a fully rendered page, search engines (Google, Bing) and social media bots (Twitter, Open Graph) can index your content accurately without needing to execute complex JavaScript.
• Perceived Performance: Users on slower devices or unstable mobile connections see the content much faster. They don't have to wait for a heavy JavaScript framework to initialize before reading the text.
• The "Best of Both Worlds": Nuxt doesn't just give you a static page. After the initial fast load, the app becomes a Page Application (SPA). This means subsequent navigations are nearly instantaneous because only the necessary data is fetched, not the whole page.

The Hydration Process

This multi-step process ensures that users see content immediately while still receiving a fully interactive experience:

• Request: The user hits the URL in their browser.
• Server: Nuxt renders the Vue components into full HTML strings on the server side.
• Response: The browser receives the pre-rendered HTML and displays the UI immediately (First Contentful Paint).
• Hydration: The browser downloads the Vue.js bundle and "takes over" the static HTML, turning it into a live, reactive application that can respond to user clicks and state changes.

To switch a Nuxt application to Single Page Application (SPA) mode, you effectively disable Server-Side Rendering (SSR) In this mode, the server sends an empty HTML shell with a tag, and the browser handles all the rendering, just like a standard Vue.js CLI or Vite project.

Method 1: Global SPA Mode

If you want the entire application to behave as an SPA, modify your nuxt.config.ts file by setting the ssr property to false.

• The server will no longer execute your Vue code.
• The application will be purely client-side.
• SEO will be limited as crawlers will see a mostly empty HTML file initially.

Method 2: Hybrid Rendering (Per-Route SPA)

Nuxt 3 allows you to keep the benefits of SSR for most of your site while making specific sections (like an admin dashboard) behave as an SPA. This is done via routeRules.

Key Considerations when Switching to SPA

Before disabling Universal Rendering, keep these technical shifts in mind to ensure your application functions as expected:

• The <ClientOnly> Component: In SPA mode, you don't strictly need this component, but it remains useful in SSR mode to wrap parts of a page that should only run in the browser (like a complex chart or a map).
• Data Fetching: In SPA mode, useFetch and useAsyncData will only run on the client. You won't see the "server-side" network call in the Nuxt logs; it will appear in the browser's Network tab instead.
• Deployment: When running npm run build for a global SPA, Nuxt will generate a static entry point (usually index.html) that can be hosted on any static web server (S3, Vercel, Netlify) without needing a Node.js environment.

Static Site Generation (SSG) is a rendering mode where Nuxt pre-renders your entire application into static HTML, CSS, and JavaScript files during the build process Instead of generating pages on-demand when a user visits (like SSR), the work is done upfront.

The resulting files are "flat" and can be hosted on any static web server or Content Delivery Network (CDN) without requiring a Node.js server.

How SSG Works in Nuxt

Static Site Generation (SSG) combines the SEO benefits of SSR with the low-cost hosting of static files:

• Build Phase: When you run nuxi generate, Nuxt crawls your routes and executes the logic for every page.
• Payload Generation: For every route (e.g., /about), Nuxt creates an index.html file and a small JSON "payload" containing the data fetched during the build.
• Deployment: You upload the .output/public folder to a host like Netlify, Vercel, or GitHub Pages.
• Client-Side Navigation: Once the first page loads, the app "hydrates" into a Single Page Application (SPA), making subsequent clicks instant.

SSG vs. Other Rendering Modes

Key Nuxt Commands for SSG

To effectively generate a static site, you need to use the specific build commands and understand how Nuxt discovers your routes:

• npx nuxi generate: This is the primary command for SSG. It builds the application and then exports it to static files.
• Dynamic Routes in SSG: For routes like /blog/[slug], Nuxt needs to know which slugs exist to generate the pages. You can provide these in nuxt.config.ts or let Nuxt crawl your <NuxtLink> tags to find them automatically.

The "Hybrid" Advantage

In Nuxt 3, you aren't forced to choose SSG for the whole site. Using Route Rules, you can make your landing pages static (SSG) for speed, while keeping your account settings page as a Single Page App (CSR).

Route Rules are the engine behind Hybrid Rendering in Nuxt 3. They allow you to define different caching and rendering strategies for different sections of your application within a single configuration file.

Instead of choosing one rendering mode for your entire app, you can assign rules to specific URL patterns (e.g.,/blog/** vs. /admin/**).

Core Rendering Strategies in Route Rules

The following table explains the different "behaviors" you can apply to routes:

How it Works: The Nitro Engine

Route Rules are processed by Nitro, Nuxt’s server engine. When a request comes in, Nitro checks the defined rules and decides whether to:

• Serve a pre-generated static file: Fast delivery from disk or CDN.
• Execute a server-side function: Renders the page fresh for every request (SSR).
• Serve a "stale" (cached) version: Delivers cached content while fetching new data in the background (SWR/ISR).

Example Configuration

In your nuxt.config.ts, you can mix these strategies to optimize performance and SEO:

Why use Route Rules?

Route Rules provide the flexibility to optimize different parts of your application based on their specific requirements:

• Granular Control: You don't sacrifice SEO on your landing pages just because your dashboard needs to be an SPA.
• Cost Efficiency: SWR and ISR reduce server load by serving cached versions of dynamic pages.
• Global Deployment: Nitro optimizes these rules for the platform you are deploying to (Vercel, Netlify, Cloudflare, etc.).

Stale-While-Revalidate (SWR) is a caching strategy that allows Nuxt to serve a page instantly from a cache (the "stale" version) while simultaneously triggering a background re-generation of that page (the "revalidate" step) to ensure the next visitor sees updated content.

It provides the speed of a static site with the flexibility of a dynamic site.

The SWR Lifecycle

When a user requests a route configured with SWR, the following process occurs:

Configuring SWR in Nuxt

You enable SWR using routeRules in your nuxt.config.ts. You can set it to true (infinite cache until a server restart) or a specific number of seconds.

Key Benefits

Implementing SWR (Stale-While-Revalidate) and ISR (Incremental Static Regeneration) provides significant advantages for high-traffic applications:

• Zero Latency: Users never wait for the server to fetch data or render HTML because they are always served from the cache.
• Reduced Server Load: The server only renders the page once per "stale" period, regardless of how many thousands of users visit.
• High Availability: If your data source (API) goes down, Nuxt will continue to serve the "stale" cached version rather than showing an error page.

SWR vs. ISR (Incremental Static Regeneration)

While very similar, the distinction in the Nuxt/Nitro ecosystem is:

• SWR: Typically focused on caching at the Edge (CDN level). It serves the stale version immediately and refreshes the content in the background for the next visitor.
• ISR: Often implies the ability to revalidate on a schedule or via a manual trigger (webhook), though in many modern hosting providers, these terms are used interchangeably.

In Nuxt 3, the useHead composable is the primary tool for managing SEO and document metadata (like title, meta, link tags) programmatically. It works both on the server and the client, ensuring that search engines see your metadata in the initial HTML.

Basic Usage of usehead

You call usehead inside the block of your page or component. It accepts an object where keys correspond to HTML head elements.

Dynamic and Reactive Metadata

Because usehead is built on top of the Unhead library, it can accept computed properties or refs. If your data changes (e.g., a product name is loaded from an API), the head tags will update automatically in the browser.

Alternative: useSeoMeta

For standard SEO tasks, Nuxt provides a more concise composable called useSeoMeta.It offers full TypeScript support for common tags, reducing the chance of typos in property names like og:description.

Best Practices for SEO in Nuxt

To maximize search engine visibility and maintain clean meta tags, follow these core implementation strategies:

• Placement: Use useHead in the pages/ directory for page-specific SEO. Use it in app.vue or a layout for global defaults.
• Server-Side Rendering: Always ensure SSR is enabled for pages where SEO is critical, as useHead ensures the tags are present in the initial HTML delivered to crawlers.
• Avoid Duplication: Nuxt automatically merges head tags. If you define a title in app.vue and another in about.vue, the page-specific one will override the global one.

While both macros/composables are used within the pages/ directory, they serve entirely different layers of the application. useSeoMeta handles what the browser and search engines see (HTML head), while definePageMeta handles how Nuxt treats the page internally (routing and logic).

Key Differences

useSeoMeta (The "External" Face)

This is a helper for SEO. It maps objects to HTML tags. It is preferred over useHead for SEO because it provides TypeScript autocomplete for over 100 social meta tags (like ogTitle, twitterCard).

This is a compiler macro. It tells Nuxt how to handle the page within the framework's ecosystem. It cannot access component state (like ref) because it is processed before the component is even instantiated.

Summary of Usage

Understanding when to use each composable is key to managing your Nuxt 3 application effectively:

• Use useSeoMeta: When you want to change what shows up on a Google Search result or a shared link on social media platforms like Twitter.
• Use definePageMeta: When you want to change which layout the page uses, protect the route with a password (middleware), or validate if a URL parameter is a number.

Implementing a sitemap in Nuxt 3 is most efficiently done using the nuxt-simple-sitemap module (now part of the Nuxt SEO suite). It automatically generates sitemap.xmlfiles based on your page structure and supports dynamic routes.

Method 1: Automatic Generation (Recommended)

For most projects, you want a sitemap that stays in sync with your pages/ directory automatically.

Handling Dynamic Routes

Since Nuxt cannot "guess" all your database-driven IDs or slugs (e.g., /products/[id]), you must provide them so they appear in the sitemap:

• Static SSG: If you use npx nuxi generate, the crawler will often find links to these pages and add them automatically.
• Dynamic/SSR: You can provide a function or an endpoint in nuxt.config.ts to fetch these IDs:

Key Features of Nuxt Sitemap

The @nuxtjs/sitemap module automates complex SEO requirements, ensuring your site remains compliant with search engine standards:

• Multi-Sitemap Support: Automatically splits your sitemaps if you have more than 50,000 URLs (SEO best practice).
• I18n Integration: If you use @nuxtjs/i18n, the sitemap automatically generates <xhtml:link> tags for different language versions of the same page.
• Automated Metadata: It uses the last modified date of the files to populate the <lastmod> tag.
• Route Exclusion: You can easily hide pages (like /admin or secret routes) from the sitemap.

Method 2: Manual (For Simple Sites)

If you prefer not to use a module, you can create a Server Route at server/routes/sitemap.xml.ts. You would then manually write the XML string and set the Content-Type header to header to. However, this requires manual maintenance as you add new pages.

Yes, Nuxt supports automatic image optimization primarily through the official Nuxt Image module (@nuxt/image). It is designed to handle the heavy lifting of resizing, compressing, and serving images in modern formats like WebP or AVIF.

By replacing the standard HTML tag with the or components, Nuxt automatically optimizes the asset based on the user's device and the provider you choose (e.g., local server, Cloudinary, Vercel).

Core Components Comparison

Key Features & Optimization Techniques

The @nuxt/image module provides powerful tools to automate image delivery and significantly improve Core Web Vitals:

• Format Conversion: Automatically converts PNG/JPG to smaller, high-quality formats like WebP or AVIF.
• Responsive Sizes: You can define a sizes attribute (e.g., sm:100vw md:50vw lg:400px), and Nuxt will generate multiple versions of the image for different screen widths.
• Lazy Loading: Images are natively lazy-loaded by default, meaning they only download when they are about to enter the viewport.
• Placeholders: Supports low-quality image placeholders (LQIP) or blurred effects while the main image loads, improving perceived performance.
• Providers: Includes built-in support for various transformation services:
  • IPX (Default): A local image processor based on Sharp.
  • External: Cloudinary, Fastly, Imgix, Vercel, and AWS.

Basic Usage Example

Implementation Steps

• Install: Run npm install @nuxt/image
• Register:Add '@nuxt/image' to the modules array in nuxt.config.ts.
• Use:Replace tags with .

Nuxt is designed as a "performance-first" framework. It addresses Core Web Vitals (CWV) by automating many of the technical optimizations that would otherwise require manual configuration in a standard Vue.js or React application.

Impact on Core Web Vitals

Key Built-in Optimizations

Nuxt automatically observes links in the viewport (using the Intersection Observer API). When a becomes visible, Nuxt pre-fetches the JavaScript and data for that page in the background. By the time the user clicks, the transition feels instantaneous.

Standard web fonts often cause layout shifts (CLS) while loading. Nuxt Fonts:

• Automatically downloads and hosts Google Fonts locally.
• Generates fallback font metrics so the "blank" space matches the final font size, eliminating jumps.

Nuxt splits your application into small chunks. If a user visits /home, the browser only downloads the JavaScript required for the homepage. This keeps the "Initial JavaScript Execution" time low, directly benefiting INP.

Nuxt 3 uses an optimized hydration process. You can use the component or Lazy Components to prevent heavy, non-essential parts of the page (like a footer or a complex modal) from delaying the initial interactive state.

The underlying server engine (Nitro) is extremely lightweight. It yields a very low TTFB (Time to First Byte), which is the foundation for a good LCP score. Whether you are on a CDN or a VPS, Nitro ensures the server responds as quickly as possible.

In Nuxt 3, both useFetch and useAsyncData are designed to handle data fetching while preventing "double-fetching" (where the server fetches data and then the client fetches it again during hydration).

The simplest way to think about them is: useFetch a high-level "shortcut," while useAsyncData the low-level "engine."

When to Use Which?

If you just need to get data from a specific endpoint, useFetch is the most efficient choice. It automatically handles the URL, reactivity, and type inference.

Use this when your data fetching involves more than just a single URL request. Common scenarios include:

• Multiple Requests: Fetching from two APIs and merging the results
• External SDKs:Using a library like cms.getEntries() or db.collection().get()
• Custom Transformations: Running heavy logic on the data before it ever reaches your component state.

A Common Mistake: $fetch alone

Many developers accidentally use $fetch (Nuxt's underlying HTTP client) inside their components without a wrapper.

• The Problem: $fetch does not save its state to the Nuxt payload. This causes the data to be fetched on the server, discarded, and then fetched again on the client.
• The Fix: Always wrap $fetch in useAsyncData if it is being called during the initial page load.

Return Values

Both composables return the exact same object structure:

• data: The result of the async function.
• pending: A boolean indicating if the data is still loading.
• refresh / execute: Functions to manually trigger a re-fetch.
• error: An error object if the request failed.
• status: A string (idle,pending, success, or error).

Choosing between$fetch and useFetch is less about "what works" and more about "where it's running." In Nuxt, the key difference is SSR safety and payload transfer.

When to Use $fetch

You should reach for $fetch when the request is event-driven and happens strictly on the client after the page has already loaded:

• Form Submissions: Sending a POST or PUT request when a user clicks "Submit."
• User Interactions: Triggering an API call on a button click (e.g., "Like" a post or "Add to Cart").
• Inside Logic/Utils: When writing a helper function that isn't a Vue component but needs to make a network request.
• API Routes: When writing your own server-side API endpoints in server/api/, you use $fetch to call other external APIs.

Why Avoid $fetch in <script setup>?

If you use await $fetch() directly in the body of your <script setup>, it triggers the following sequence:

• On the Server: Nuxt fetches the data to render the initial HTML.
• On the Client: During hydration, the browser executes the same script. Since $fetch doesn't save its result to the Nuxt "payload," the browser calls the API again.
• On The Result: Your server is hit twice, which can lead to "hydration mismatches" where the client data flashes or overwrites the server data.

Summary: Rule of Thumb

• Initial Page Data? Use useFetch
• User Clicked a Button? Use $fetch.
• Complex Logic + SSR? Use useAsyncData(() => $fetch(...)).

To handle API errors globally in Nuxt 3, you should use interceptors within a custom fetch instance. Nuxt uses ofetch under the hood, which provides lifecycle hooks like onResponseError to catch errors across your entire app.

The most robust pattern is to create a custom fetch composable that wraps your logic in one place.

Step 1: Create a Custom Fetch Plugin

First, create a plugin to define a global API instance with interceptors. This is where you handle specific status codes (like 401 Unauthorized).

Step 2: Create a Custom Composable

To make this instance easy to use with Nuxt's SSR-friendly useFetch , wrap it in a composable.

Bonus: The NuxtErrorBoundary Component

If you want to prevent a single component's API failure from breaking the entire page, use the built-in boundary component.

useState is a Nuxt-specific composable used for creating SSR-friendly reactive state. While it looks and behaves similarly to a standard Vue ref, it is specifically designed to solve the challenges of hydration and cross-request state pollution in a server-side rendered environment.

Key Differences: useState vs. Standard ref

Why You Need useState for SSR

If you use ref(Math.random()) in a component, the server will generate one number, and the client will generate a different one during hydration. This causes a "Hydration Mismatch" error. useState ensures the client picks up the exact same value the server generated.

In a standard Vue SPA, a global ref is fine because each user has their own browser. However, on a Nuxt server, a ref defined outside a component becomes a singleton shared by every user visiting the site. This could lead to User A seeing User B's private data. useState prevents this by scoping state to the specific request.

When to Use Each

• Use ref: For local, temporary UI state that doesn't need to be shared or persisted from the server (e.g., aisMenuOpen toggle).
• Use useState: For any state that needs to be shared across components or must be identical on both server and client (e.g., user authentication status, theme preferences).

Yes, Pinia is the officially recommended state management library for Nuxt 3. While Nuxt provides useState for simple shared state, Pinia is preferred for large-scale applications that require organized, complex logic and developer tools support.

Setting Up Pinia in Nuxt

Nuxt makes integration seamless through the @pinia/nuxtmodule.

Configuration: Add it to you modules in nuxt.config.ts.

Usage: Define a store in the stores/ directory (Nuxt will auto-import it).

Crucial Rule: SSR Safety

When using Pinia with Nuxt (SSR), you must follow two rules to avoid State Leakage (where one user sees another user's data):

• Avoid Global Stores:Never define a store instance outside of a function. Always use defineStore.
• Use the Composition API:Inside your components, always call the store hook inside setup or .

Why use Pinia in Nuxt?

• Server-to-Client Transfer: Like useState, Pinia handles the serialization of state. The server fetches the data, populates the store, and the client "hydrates" that exact state without re-fetching.
• Modularization: It allows you to separate your business logic from your Vue components.
• HMR (Hot Module Replacement) You can edit your stores without reloading the entire page or losing the current state.

A Hydration Mismatch occurs when the DOM structure or data rendered on the server does not exactly match the DOM structure or data generated by the client during its first render.

Nuxt detects this discrepancy and "bail out" of hydration, which can lead to broken event listeners, flickering UI, or slower performance.

Common Causes and Fixes

Strategic Solutions

If you need a random ID or a timestamp that remains identical on both sides, useState is mandatory. It serializes the value into the HTML payload so the client doesn't re-calculate it.

For components that rely heavily on browser-specific features (like a complex data table or a window-width listener), wrap them in . You can also provide a placeholder to show during SSR to prevent layout shifts.

Logic inside Logic insideonly runs in the browser. Use this to modify state that depends on window or document

How to Debug Mismatches

• Nuxt DevTools: Open the DevTools in your browser; it often highlights exactly which element caused the hydration error.
• Console Logs: Chrome will typically log: "Hydration completed but contains mismatches." It will then list the expected vs. actual HTML.
• View Source: Right-click and "View Page Source." Compare that static HTML with what you see in the "Elements" tab of your inspector.

The "Last Resort" Attribute

If you have a specific element that you know will be different (and you're okay with it), you can use the data-hydration-uid or the Vue-specific suppressHydrationWarnin attribute, though this should be avoided if possible.

In Nuxt 3, useFetch (and useAsyncData) returns a set of helper functions specifically designed for manual re-execution. The primary method for this is the refresh function (also aliased as execute).

Ways to Trigger a Refresh

There are three main ways to re-trigger a data fetch: using the returned function, using a reactive dependency, or using a global utility.

1. Manual Refresh (The Function Call)

When you call useFetch, destructure the refresh function. You can then call this inside any event handler.

2. Automatic Refresh (Reactive Watch)

If your API call depends on a reactive variable (like a page number or search query), use the watch option. When the variable changes, useFetch automatically re-executes.

3. Global Refresh (refreshNuxtData)

Sometimes you need to refresh data in a parent component after an action in a child component (like refreshing a list after deleting an item). You can target a specific useFetch call using its unique key.

Key Considerations

• refresh vs. execute: These are essentially the same. execute is often used when { immediate: false } is set in the options, meaning the fetch doesn't run until you manually call it.
• Pending State: The pending ref returned by useFetch will switch back to true every time refresh is called, allowing you to show loading spinners during updates.
• Data Deduplication: If multiple components are listening to the same key, calling refreshNuxtData will update all of them simultaneously with a single network request.

In Nuxt 3, the "Lazy" version of data fetching allows your application to navigate to a new page immediately, without waiting for the data to finish loading on the client side.

By default, useFetch blocks the navigation (the browser "hangs" for a split second) until the data is resolved. useLazyFetch breaks this block, making the UI feel more responsive.

useFetch vs useLazyFetch

How it Works in Practice

When you use useLazyFetch, you must handle the "loading" state in your template, otherwise your app might try to render data that doesn't exist yet, leading to errors.

Why Use Lazy Fetching?

• Perceived Speed: Users see the layout and navigation elements immediately, which feels faster than staring at a loading bar on the previous page.
• Hybrid Importance: If you have a sidebar that loads data from a slow API, using useLazyFetch ensures the main content of your page isn't delayed by that slow sidebar.
• Client-Side Navigation: It is particularly effective for Single Page Application (SPA) transitions where you want the "feel" of an instant app.

Key Limitation: SEO & Meta Tags

Do not use lazy fetching for data required for SEO. Because useLazyFetchdoes not block the render, if you are using the fetched data to populate useHead(like a page title or meta description), search engine crawlers might see the "Loading..." state instead of your actual content. Use standard useFetch for any data that must be present in the initial HTML.

The "Lazy" Macro

You can achieve the same result using the lazyoption in the standard composables:

• useLazyFetch(url) is identical to useFetch(url, { lazy: true }).
• useLazyAsyncData(key, fn) is identical to useAsyncData(key, fn, { lazy: true }).

In Nuxt 3, passing headers or authentication tokens during Server-Side Rendering (SSR) requires specific care. Unlike the browser, which automatically attaches cookies to requests, the Nuxt server acts as a "proxy" and does not share the user's browser state unless you manually forward it.

1. Forwarding Client Headers (Browser ? Nuxt Server ? API)

If your API relies on cookies or headers (like Authorization) that the browser originally sent to Nuxt, you must "proxy" them using the useRequestHeaders composable.

2. Attaching Authentication Tokens (Manual)

When using JWT tokens stored in a cookie or state, you should attach them using the Authorization header.

The useRequestFetch Pattern

For more advanced scenarios, Nuxt provides useRequestFetch. This utility creates a version of $fetch This utility creates a version of

• When to use: When you are calling an internal Nuxt API route (/api/...) from within useAsyncData.
• Advantage: It handles the "context forwarding" automatically so you don't have to manually map headers.

Security Warning: Avoid Header Leakage

Be extremely careful when using useRequestHeaders() with external APIs. If you forward all client headers to a third-party service, you might accidentally leak sensitive user cookies or internal server headers to an untrusted source.

Tip:Always whitelist only the specific headers your API needs (e.g., 'cookie', 'authorization').

Nuxt 3 leverages its powerful server engine, Nitro, to provide a multi-layered caching system. This allows you to cache everything from entire HTML pages down to individual server functions or raw API responses.

The caching strategy you choose depends on whether you want to cache the entire route, an API endpoint, or a specific expensive function.

1. Route-Level Caching (Hybrid Rendering)

The simplest way to cache is through routeRules in nuxt.config.ts. This tells the server how to treat specific URL patterns without writing any custom server code.

2. API & Event Handler Caching

If you have custom API routes in server/api/, you can use Nitro's specialized handlers to cache their JSON responses.

• defineCachedEventHandler: Wraps an entire API route. The first user triggers the logic; subsequent users get the cached JSON result.
• defineCachedFunction: Caches the result of a specific utility function used within multiple handlers.

3. Low-Level Storage (useStorage)

For manual control, Nuxt provides a unified Storage Layer called unstorage. You can get, set, and expire data manually using different "drivers" (Memory, Redis, Filesystem).

Nuxt Modules are the building blocks of the Nuxt ecosystem. They are essentially functions that run sequentially when Nuxt starts in development mode or during the build process. Their primary purpose is to automate the configuration and extension of your application.

Instead of manually configuring 10 different files to add a feature like Tailwind CSS or a Sitemap, a module handles the setup for you in a single line.

How Modules Extend Nuxt

Modules have deep access to the Nuxt "hooks," allowing them to modify almost any part of the framework's behavior.

The Three Types of Modules

• Official Modules: Maintained by the Nuxt team (e.g., @nuxt/image, @nuxt/content, @nuxt/ui).
• Community Modules:: Maintained by the open-source community (e.g.,lucide-nuxt, nuxt-simple-sitemap).
• Local Modules:: Custom logic written inside your own project (usually in a modules/ folder) to keep your nuxt.config.ts.

Using a Module

To use a module, you typically follow a two-step process:

• Install the package:: npm install @nuxtjs/tailwindcss
• Register it:: Add it to the modules array in nuxt.config.ts.

Why Not Just Use Plugins?

While they sound similar, they serve different stages of the lifecycle:

• Plugins: Run at runtime (when the app starts in the browser or on the server). Use them for things like global directives or injecting variables into the Vue instance.
• Modules: Run at build-time. Use them to change the actual structure of the app, add files, or configure the build engine.

The Module Builder

If you want to create your own module to share with others, Nuxt provides a starter kit called nuxt-module-builder. It streamlines the process of writing, testing, and publishing a module to the official Nuxt Modules directory.

Creating a custom Nuxt module allows you to encapsulate reusable logic, register components, or hook into the Nuxt lifecycle. You can create a local module for a single project or use the Starter Kit to build a package for NPM.

1. Creating a Simple Local Module

For internal project logic, you don't need a complex setup. You can define a module directly in your modules/ directory.

File: modules/hello-world.ts

2. Using the Official Starter Kit (For Distribution)

If you intend to share your module via NPM, use the official template. It includes a src/ directory for logic and a playground/ directory for live testing.

npx nuxi init -t module my-awesome-module

Standard Module Structure:

• | src/module.ts | The main entry point where you define hooks and configuration. |
• | src/runtime/ | Contains code that will be injected into the user's app (plugins, components). |
• | playground/ | A mini Nuxt app to test your module in real-time. |
• | package.json | Manages dependencies and metadata (name, version). |

3. Common Module Tasks

Modules extend the framework by using Nuxt Kit>> utilities.

• Adding a Component: addComponent({ name: 'MyButton', filePath: resolver.resolve('./runtime/MyButton.vue') })
• Injecting a Composable: addImports({ name: 'useMyTool', from: resolver.resolve('./runtime/composables') })
• Hooking into Nuxt:

4. Key Differences: Local vs. Published

• Local: Registered innuxt.config.ts via relative path (e.g., '~/modules/my-module'). Perfect for site-specific optimizations.
• Published:Installed via npm install and registered by package name. Requires proper bundling usingnpm run prepack.

While both Modules and Plugins are used to extend Nuxt, they operate at completely different stages of the application lifecycle. The simplest way to remember the difference is: Modules happen at "Build-time" (when you run npm run dev or build), while Plugins happen at "Runtime" (when the user actually opens the page).

Core Comparison Table

When to Use a Module

Use a Module if you need to change how Nuxt works or if you want to bundle multiple features together.

• Automating Setup: Add tools like Tailwind CSS and configure them automatically without requiring manual setup from the user doing it manually.
• Adding Components/Composables: Provide a reusable library of UI components or composables that are auto-imported into the app.
• Modifying the Build: You need to change how Vite processes specific file types (like SVG or YAML).
• Nitro Configuration: Inject server-side middleware, storage drivers, or modify Nitro configuration globally.

When to Use a Plugin

Use a Plugin if you need to provide something to your Vue components or handle logic during page load.

• External Libraries: Initialize libraries that require access to the DOM or Vue instance (e.g., tooltip libraries or Google Analytics).
• Global Helpers: Create reusable helpers like $formatDate that are available in every component via useNuxtApp().
• Injected Keys: Providing a specific value (like a global configuration object) that components can inject.
• Route Middleware: Attaching logic that runs specifically when the router initializes

The "Parent-Child" Relationship

The "Parent-Child" Relationship Module to install a Plugin.

• Example: The @nuxtjs/supabase Module configures the project and then injects a Plugin so that you can use const supabase = useSupabaseClient() inside your components.

To register a third-party library globally in Nuxt 3, you create a file in the plugins/ directory. Nuxt automatically scans this folder and initializes these files during the application's startup.

Depending on the library, you might need to register it as a Vue Plugin (using .use()) or provide it as a helper accessible throughout your app via useNuxtApp().

Common Registration Patterns

Implementation Examples

If you are using a library like Floating Vue for tooltips, you register it directly to the Vue instance.

File: plugins/floating-vue.ts

If you want to make a library like LDAP or a custom Analytics instance available everywhere.

File: plugins/analytics.ts

Many third-party libraries (like Chart.js or Google Maps) require access to the window or document objects. If these run on the server, the app will crash. You can control this using file suffixes:

• my-plugin.client.ts: Runs only on the browser side.
• my-plugin.server.ts: Runs only on the server side.

Best Practices

Follow these best practices when working with plugins in Nuxt:

• Avoid Overuse: Every plugin adds to the "Initial Bundle Size." Only register libraries globally if they are used on almost every page.
• Tree Shaking: If a library supports it, prefer importing it locally within the component where it is needed instead of a global plugin.
• Order Matters: If one plugin depends on another, prefix filenames with numbers (e.g., 01.auth.ts, 02.api.ts) to control execution order.

The server/ directory is what makes Nuxt 3 a full-stack framework. It allows you to write backend logic—like API endpoints, database connections, and server-side security—directly within your Nuxt project.

Everything in this folder is powered by Nitro, Nuxt's high-performance server engine, and it runs in a Node.js (or Edge) environment, completely separate from your Vue frontend code.

1. The api/ Directory (File-Based API)

Any file you place here automatically becomes an API endpoint. You use defineEventHandler to process requests.

• Result: Sending a GET request to /api/hello returns the JSON object above.
• Method Support: You can specify methods using suffixes like hello.get.ts or user.post.ts.

2. Server Middleware

Unlike frontend route middleware, server middleware runs for every single request made to the server (including requests for images or static assets). It's the perfect place for:

• Logging requests.
• Checking authentication headers.
• Adding custom context to the event object.

3. Why Use the server/ Folder?

• Security: Keep sensitive data like API keys or database credentials hidden from the browser.
• Full-Stack Power: Handle tasks such as sending emails or processing Stripe payments without needing a separate backend like Express or Laravel.
• Type Safety: Nuxt auto-generates TypeScript types for API routes, so useFetch('/api/hello') knows exactly what data is returned.
• Performance: Nitro is highly optimized and can be deployed to serverless platforms like Vercel, Netlify, or Edge workers such as Cloudflare.

The "Server Utils" Advantage

Files in server/utils/ are auto-imported within your server handlers. If you create a database connection utility there, you can use it in any file inside server/api/ without a single import statement.

In Nuxt 3, API routes are created by placing files inside the server/api/ directory. These routes are powered by Nitro and use a file-based routing system similar to your Vue pages.

Every API route must export a defineEventHandler function. This function receives an event object, which contains the request, response, and various utilities.

• Endpoint: /api/hello
• Response: { "message": "Hello from Nitro!" }

Handling Different HTTP Methods

You can handle specific methods (GET, POST, DELETE, etc.) by either checking the method inside the handler or using the filename suffix.

Nitro provides several built-in utilities to extract data from the incoming request

1. Query Parameters

For URLs like /api/search?q=nuxt, use getQuery.

2. Request Body (POST/PUT)

To read JSON data sent in a request body, use readBody.

3. Route Parameters (Dynamic API)

For dynamic paths like /api/users/123, name your file server/api/users/[id].ts and use event.context.params.

Advanced API Features

• Error Handling: Use createError to return specific HTTP status codes.
• Runtime Config: Access your private environment variables using useRuntimeConfig(event).
• Cookies: Use getCookie(event, 'name') and setCookie(event, 'name', value) to manage sessions.