@nuxt/docs 0.0.0 → 3.17.0

package/2.guide/1.concepts/3.rendering.md

@@ -0,0 +1,255 @@
+---
+title: 'Rendering Modes'
+description: 'Learn about the different rendering modes available in Nuxt.'
+---
+
+Nuxt supports different rendering modes, [universal rendering](#universal-rendering), [client-side rendering](#client-side-rendering) but also offers [hybrid-rendering](#hybrid-rendering) and the possibility to render your application on [CDN Edge Servers](#edge-side-rendering).
+
+Both the browser and server can interpret JavaScript code to turn Vue.js components into HTML elements. This step is called **rendering**. Nuxt supports both **universal** and **client-side** rendering. The two approaches have benefits and downsides that we will cover.
+
+By default, Nuxt uses **universal rendering** to provide better user experience, performance and to optimize search engine indexing, but you can switch rendering modes in [one line of configuration](/docs/api/nuxt-config#ssr).
+
+## Universal Rendering
+
+This step is similar to traditional **server-side rendering** performed by PHP or Ruby applications. When the browser requests a URL with universal rendering enabled, Nuxt runs the JavaScript (Vue.js) code in a server environment and returns a fully rendered HTML page to the browser. Nuxt may also return a fully rendered HTML page from a cache if the page was generated in advance. Users immediately get the entirety of the initial content of the application, contrary to client-side rendering.
+
+Once the HTML document has been downloaded, the browser interprets this and Vue.js takes control of the document. The same JavaScript code that once ran on the server runs on the client (browser) **again** in the background now enabling interactivity (hence **Universal rendering**) by binding its listeners to the HTML. This is called **Hydration**. When hydration is complete, the page can enjoy benefits such as dynamic interfaces and page transitions.
+
+Universal rendering allows a Nuxt application to provide quick page load times while preserving the benefits of client-side rendering. Furthermore, as the content is already present in the HTML document, crawlers can index it without overhead.
+
+![Users can access the static content when the HTML document is loaded. Hydration then allows page's interactivity](/assets/docs/concepts/rendering/ssr.svg)
+
+**What's server-rendered and what's client-rendered?**
+
+It is normal to ask which parts of a Vue file runs on the server and/or the client in universal rendering mode.
+
+```vue [app.vue]
+<script setup lang="ts">
+const counter = ref(0); // executes in server and client environments
+
+const handleClick = () => {
+  counter.value++; // executes only in a client environment
+};
+</script>
+
+<template>
+  <div>
+    <p>Count: {{ counter }}</p>
+    <button @click="handleClick">Increment</button>
+  </div>
+</template>
+```
+
+On the initial request, the `counter` ref is initialized in the server since it is rendered inside the `<p>` tag. The contents of `handleClick` is never executed here. During hydration in the browser, the `counter` ref is re-initialized. The `handleClick` finally binds itself to the button; Therefore it is reasonable to deduce that the body of `handleClick` will always run in a browser environment.
+
+[Middlewares](/docs/guide/directory-structure/middleware) and [pages](/docs/guide/directory-structure/pages) run in the server and on the client during hydration. [Plugins](/docs/guide/directory-structure/plugins) can be rendered on the server or client or both. [Components](/docs/guide/directory-structure/components) can be forced to run on the client only as well. [Composables](/docs/guide/directory-structure/composables) and [utilities](/docs/guide/directory-structure/utils) are rendered based on the context of their usage.
+
+**Benefits of server-side rendering:**
+- **Performance**: Users can get immediate access to the page's content because browsers can display static content much faster than JavaScript-generated content. At the same time, Nuxt preserves the interactivity of a web application during the hydration process.
+- **Search Engine Optimization**: Universal rendering delivers the entire HTML content of the page to the browser as a classic server application. Web crawlers can directly index the page's content, which makes Universal rendering a great choice for any content that you want to index quickly.
+
+**Downsides of server-side rendering:**
+- **Development constraints:** Server and browser environments don't provide the same APIs, and it can be tricky to write code that can run on both sides seamlessly. Fortunately, Nuxt provides guidelines and specific variables to help you determine where a piece of code is executed.
+- **Cost:** A server needs to be running in order to render pages on the fly. This adds a monthly cost like any traditional server. However, the server calls are highly reduced thanks to universal rendering with the browser taking over on client-side navigation. A cost reduction is possible by leveraging [edge-side-rendering](#edge-side-rendering).
+
+Universal rendering is very versatile and can fit almost any use case, and is especially appropriate for any content-oriented websites: **blogs, marketing websites, portfolios, e-commerce sites, and marketplaces.**
+
+::tip
+For more examples about writing Vue code without hydration mismatch, see [the Vue docs](https://vuejs.org/guide/scaling-up/ssr.html#hydration-mismatch).
+::
+
+::important
+When importing a library that relies on browser APIs and has side effects, make sure the component importing it is only called client-side. Bundlers do not treeshake imports of modules containing side effects.
+::
+
+## Client-Side Rendering
+
+Out of the box, a traditional Vue.js application is rendered in the browser (or **client**). Then, Vue.js generates HTML elements after the browser downloads and parses all the JavaScript code containing the instructions to create the current interface.
+
+![Users have to wait for the browser to download, parse and execute the JavaScript before seeing the page's content](/assets/docs/concepts/rendering/csr.svg)
+
+**Benefits of client-side rendering:**
+- **Development speed**: When working entirely on the client-side, we don't have to worry about the server compatibility of the code, for example, by using browser-only APIs like the `window` object.
+- **Cheaper:** Running a server adds a cost of infrastructure as you would need to run on a platform that supports JavaScript. We can host Client-only applications on any static server with HTML, CSS, and JavaScript files.
+- **Offline:** Because code entirely runs in the browser, it can nicely keep working while the internet is unavailable.
+
+**Downsides of client-side rendering:**
+- **Performance**: The user has to wait for the browser to download, parse and run JavaScript files. Depending on the network for the download part and the user's device for the parsing and execution, this can take some time and impact the user's experience.
+- **Search Engine Optimization**: Indexing and updating the content delivered via client-side rendering takes more time than with a server-rendered HTML document. This is related to the performance drawback we discussed, as search engine crawlers won't wait for the interface to be fully rendered on their first try to index the page. Your content will take more time to show and update in search results pages with pure client-side rendering.
+
+Client-side rendering is a good choice for heavily interactive **web applications** that don't need indexing or whose users visit frequently. It can leverage browser caching to skip the download phase on subsequent visits, such as **SaaS, back-office applications, or online games**.
+
+You can enable client-side only rendering with Nuxt in your `nuxt.config.ts`:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  ssr: false
+})
+```
+
+::note
+If you do use `ssr: false`, you should also place an HTML file in `~/app/spa-loading-template.html` with some HTML you would like to use to render a loading screen that will be rendered until your app is hydrated.
+:read-more{title="SPA Loading Template" to="/docs/api/configuration/nuxt-config#spaloadingtemplate"}
+::
+
+:video-accordion{title="Watch a video from Alexander Lichter about Building a plain SPA with Nuxt" videoId="7Lr0QTP1Ro8"}
+
+### Deploying a Static Client-Rendered App
+
+If you deploy your app to [static hosting](/docs/getting-started/deployment#static-hosting) with the `nuxi generate` or `nuxi build --prerender` commands, then by default, Nuxt will render every page as a separate static HTML file.
+
+::warning
+If you prerender your app with the `nuxi generate` or `nuxi build --prerender` commands, then you will not be able to use any server endpoints as no server will be included in your output folder. If you need server functionality, use `nuxi build` instead.
+::
+
+If you are using purely client-side rendering, then this might be unnecessary. You might only need a single `index.html` file, plus `200.html` and `404.html` fallbacks, which you can tell your static web host to serve up for all requests.
+
+In order to achieve this we can change how the routes are prerendered. Just add this to [your hooks](/docs/api/advanced/hooks#nuxt-hooks-build-time) in your `nuxt.config.ts`:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  hooks: {
+    'prerender:routes' ({ routes }) {
+      routes.clear() // Do not generate any routes (except the defaults)
+    }
+  },
+})
+```
+
+This will produce three files:
+
+- `index.html`
+- `200.html`
+- `404.html`
+
+The `200.html` and `404.html` might be useful for the hosting provider you are using.
+
+#### Skipping Client Fallback Generation
+
+When prerendering a client-rendered app, Nuxt will generate `index.html`, `200.html` and `404.html` files by default. However, if you need to prevent any (or all) of these files from being generated in your build, you can use the `'prerender:generate'` hook from [Nitro](/docs/getting-started/prerendering#prerendergenerate-nitro-hook).
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  ssr: false,
+  nitro: {
+    hooks: {
+      'prerender:generate'(route) {
+        const routesToSkip = ['/index.html', '/200.html', '/404.html']
+        if (routesToSkip.includes(route.route)) {
+          route.skip = true
+        }
+      }
+    }
+  }
+})
+```
+
+## Hybrid Rendering
+
+Hybrid rendering allows different caching rules per route using **Route Rules** and decides how the server should respond to a new request on a given URL.
+
+Previously every route/page of a Nuxt application and server must use the same rendering mode, universal or client-side. In various cases, some pages could be generated at build time, while others should be client-side rendered. For example, think of a content website with an admin section. Every content page should be primarily static and generated once, but the admin section requires registration and behaves more like a dynamic application.
+
+Nuxt includes route rules and hybrid rendering support. Using route rules you can define rules for a group of nuxt routes, change rendering mode or assign a cache strategy based on route!
+
+Nuxt server will automatically register corresponding middleware and wrap routes with cache handlers using [Nitro caching layer](https://nitro.unjs.io/guide/cache).
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  routeRules: {
+    // Homepage pre-rendered at build time
+    '/': { prerender: true },
+    // Products page generated on demand, revalidates in background, cached until API response changes
+    '/products': { swr: true },
+    // Product pages generated on demand, revalidates in background, cached for 1 hour (3600 seconds)
+    '/products/**': { swr: 3600 },
+    // Blog posts page generated on demand, revalidates in background, cached on CDN for 1 hour (3600 seconds)
+    '/blog': { isr: 3600 },
+    // Blog post page generated on demand once until next deployment, cached on CDN
+    '/blog/**': { isr: true },
+    // Admin dashboard renders only on client-side
+    '/admin/**': { ssr: false },
+    // Add cors headers on API routes
+    '/api/**': { cors: true },
+    // Redirects legacy urls
+    '/old-page': { redirect: '/new-page' }
+  }
+})
+```
+
+### Route Rules
+
+The different properties you can use are the following:
+- `redirect: string`{lang=ts} - Define server-side redirects.
+- `ssr: boolean`{lang=ts} - Disables server-side rendering of the HTML for sections of your app and make them render only in the browser with `ssr: false`
+- `cors: boolean`{lang=ts} - Automatically adds cors headers with `cors: true` - you can customize the output by overriding with `headers`
+- `headers: object`{lang=ts} - Add specific headers to sections of your site - for example, your assets
+- `swr: number | boolean`{lang=ts} - Add cache headers to the server response and cache it on the server or reverse proxy for a configurable TTL (time to live). The `node-server` preset of Nitro is able to cache the full response. When the TTL expired, the cached response will be sent while the page will be regenerated in the background. If true is used, a `stale-while-revalidate` header is added without a MaxAge.
+- `isr: number | boolean`{lang=ts} - The behavior is the same as `swr` except that we are able to add the response to the CDN cache on platforms that support this (currently Netlify or Vercel). If `true` is used, the content persists until the next deploy inside the CDN.
+- `prerender: boolean`{lang=ts} - Prerenders routes at build time and includes them in your build as static assets
+- `noScripts: boolean`{lang=ts} - Disables rendering of Nuxt scripts and JS resource hints for sections of your site.
+- `appMiddleware: string | string[] | Record<string, boolean>`{lang=ts} - Allows you to define middleware that should or should not run for page paths within the Vue app part of your application (that is, not your Nitro routes)
+
+Whenever possible, route rules will be automatically applied to the deployment platform's native rules for optimal performances (Netlify and Vercel are currently supported).
+
+::important
+Note that Hybrid Rendering is not available when using [`nuxt generate`](/docs/api/commands/generate).
+::
+
+**Examples:**
+
+::card-group
+  ::card
+  ---
+  icon: i-simple-icons-github
+  title: Nuxt Vercel ISR
+  to: https://github.com/danielroe/nuxt-vercel-isr
+  target: _blank
+  ui.icon.base: text-black dark:text-white
+  ---
+  Example of a Nuxt application with hybrid rendering deployed on Vercel.
+  ::
+::
+
+## Edge-Side Rendering
+
+Edge-Side Rendering (ESR) is a powerful feature introduced in Nuxt that allows the rendering of your Nuxt application closer to your users via edge servers of a Content Delivery Network (CDN). By leveraging ESR, you can ensure improved performance and reduced latency, thereby providing an enhanced user experience.
+
+With ESR, the rendering process is pushed to the 'edge' of the network - the CDN's edge servers. Note that ESR is more a deployment target than an actual rendering mode.
+
+When a request for a page is made, instead of going all the way to the original server, it's intercepted by the nearest edge server. This server generates the HTML for the page and sends it back to the user. This process minimizes the physical distance the data has to travel, **reducing latency and loading the page faster**.
+
+Edge-side rendering is possible thanks to [Nitro](https://nitro.unjs.io), the [server engine](/docs/guide/concepts/server-engine) that powers Nuxt. It offers cross-platform support for Node.js, Deno, Cloudflare Workers, and more.
+
+The current platforms where you can leverage ESR are:
+- [Cloudflare Pages](https://pages.cloudflare.com) with zero configuration using the git integration and the `nuxt build` command
+- [Vercel Edge Functions](https://vercel.com/features/edge-functions) using the `nuxt build` command and `NITRO_PRESET=vercel-edge` environment variable
+- [Netlify Edge Functions](https://www.netlify.com/products/#netlify-edge-functions) using the `nuxt build` command and `NITRO_PRESET=netlify-edge` environment variable
+
+Note that **Hybrid Rendering** can be used when using Edge-Side Rendering with route rules.
+
+You can explore open source examples deployed on some of the platform mentioned above:
+::card-group
+  ::card
+  ---
+  icon: i-simple-icons-github
+  title: Nuxt Todos Edge
+  to: https://github.com/atinux/nuxt-todos-edge
+  target: _blank
+  ui.icon.base: text-black dark:text-white
+  ---
+  A todos application with user authentication, SSR and SQLite.
+  ::
+  ::card
+  ---
+  icon: i-simple-icons-github
+  title: Atinotes
+  to: https://github.com/atinux/atinotes
+  target: _blank
+  ui.icon.base: text-black dark:text-white
+  ---
+  An editable website with universal rendering based on Cloudflare KV.
+  ::
+::
+
+<!-- TODO: link to templates with ESR category for examples -->

package/2.guide/1.concepts/4.server-engine.md

@@ -0,0 +1,62 @@
+---
+title: Server Engine
+description: 'Nuxt is powered by a new server engine: Nitro.'
+---
+
+While building Nuxt, we created a new server engine: [Nitro](https://nitro.unjs.io).
+
+It is shipped with many features:
+
+- Cross-platform support for Node.js, browsers, service workers and more.
+- Serverless support out-of-the-box.
+- API routes support.
+- Automatic code-splitting and async-loaded chunks.
+- Hybrid mode for static + serverless sites.
+- Development server with hot module reloading.
+
+## API Layer
+
+Server [API endpoints](/docs/guide/directory-structure/server#api-routes) and [Middleware](/docs/guide/directory-structure/server#server-middleware) are added by Nitro that internally uses [h3](https://github.com/unjs/h3).
+
+Key features include:
+
+- Handlers can directly return objects/arrays for an automatically-handled JSON response
+- Handlers can return promises, which will be awaited (`res.end()` and `next()` are also supported)
+- Helper functions for body parsing, cookie handling, redirects, headers and more
+
+Check out [the h3 docs](https://github.com/unjs/h3) for more information.
+
+::read-more{to="/docs/guide/directory-structure/server#server-routes"}
+Learn more about the API layer in the `server/` directory.
+::
+
+## Direct API Calls
+
+Nitro allows 'direct' calling of routes via the globally-available [`$fetch`](/docs/api/utils/dollarfetch) helper. This will make an API call to the server if run on the browser, but will directly call the relevant function if run on the server, **saving an additional API call**.
+
+[`$fetch`](/docs/api/utils/dollarfetch) API is using [ofetch](https://github.com/unjs/ofetch), with key features including:
+
+- Automatic parsing of JSON responses (with access to raw response if needed)
+- Request body and params are automatically handled, with correct `Content-Type` headers
+
+For more information on `$fetch` features, check out [ofetch](https://github.com/unjs/ofetch).
+
+## Typed API Routes
+
+When using API routes (or middleware), Nitro will generate typings for these routes as long as you are returning a value instead of using `res.end()` to send a response.
+
+You can access these types when using [`$fetch()`](/docs/api/utils/dollarfetch) or [`useFetch()`](/docs/api/composables/use-fetch).
+
+## Standalone Server
+
+Nitro produces a standalone server dist that is independent of `node_modules`.
+
+The server in Nuxt 2 is not standalone and requires part of Nuxt core to be involved by running `nuxt start` (with the [`nuxt-start`](https://www.npmjs.com/package/nuxt-start) or [`nuxt`](https://www.npmjs.com/package/nuxt) distributions) or custom programmatic usage, which is fragile and prone to breakage and not suitable for serverless and service worker environments.
+
+Nuxt generates this dist when running `nuxt build` into a [`.output`](/docs/guide/directory-structure/output) directory.
+
+The output contains runtime code to run your Nuxt server in any environment (including experimental browser service workers!) and serve your static files, making it a true hybrid framework for the JAMstack. In addition, Nuxt implements a native storage layer, supporting multi-source drivers and local assets.
+
+::read-more{icon="i-simple-icons-github" to="https://github.com/nitrojs/nitro" target="_blank"}
+Read more about Nitro engine on GitHub.
+::

package/2.guide/1.concepts/5.modules.md

@@ -0,0 +1,48 @@
+---
+title: 'Modules'
+description: "Nuxt provides a module system to extend the framework core and simplify integrations."
+---
+
+## Exploring Nuxt Modules
+
+When developing production-grade applications with Nuxt you might find that the framework's core functionality is not enough. Nuxt can be extended with configuration options and plugins, but maintaining these customizations across multiple projects can be tedious, repetitive and time-consuming. On the other hand, supporting every project's needs out of the box would make Nuxt very complex and hard to use.
+
+This is one of the reasons why Nuxt provides a module system that makes it possible to extend the core. Nuxt modules are async functions that sequentially run when starting Nuxt in development mode using [`nuxi dev`](/docs/api/commands/dev) or building a project for production with [`nuxi build`](/docs/api/commands/build). They can override templates, configure webpack loaders, add CSS libraries, and perform many other useful tasks.
+
+Best of all, Nuxt modules can be distributed in npm packages. This makes it possible for them to be reused across projects and shared with the community, helping create an ecosystem of high-quality add-ons.
+
+::read-more{to="/modules"}
+Explore Nuxt Modules
+::
+
+## Add Nuxt Modules
+
+Once you have installed the modules you can add them to your [`nuxt.config.ts`](/docs/guide/directory-structure/nuxt-config) file under the `modules` property. Module developers usually provide additional steps and details for usage.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: [
+    // Using package name (recommended usage)
+    '@nuxtjs/example',
+
+    // Load a local module
+    './modules/example',
+
+    // Add module with inline-options
+    ['./modules/example', { token: '123' }],
+
+    // Inline module definition
+    async (inlineOptions, nuxt) => { }
+  ]
+})
+```
+
+::warning
+Nuxt modules are now build-time-only, and the `buildModules` property used in Nuxt 2 is deprecated in favor of `modules`.
+::
+
+## Create a Nuxt Module
+
+Everyone has the opportunity to develop modules and we cannot wait to see what you will build.
+
+:read-more{to="/docs/guide/going-further/modules" title="Module Author Guide"}

package/2.guide/1.concepts/7.esm.md

@@ -0,0 +1,299 @@
+---
+title: 'ES Modules'
+description: "Nuxt uses native ES modules."
+---
+
+This guide helps explain what ES Modules are and how to make a Nuxt app (or upstream library) compatible with ESM.
+
+## Background
+
+### CommonJS Modules
+
+CommonJS (CJS) is a format introduced by Node.js that allows sharing functionality between isolated JavaScript modules ([read more](https://nodejs.org/api/modules.html)).
+You might be already familiar with this syntax:
+
+```js
+const a = require('./a')
+
+module.exports.a = a
+```
+
+Bundlers like webpack and Rollup support this syntax and allow you to use modules written in CommonJS in the browser.
+
+### ESM Syntax
+
+Most of the time, when people talk about ESM vs. CJS, they are talking about a different syntax for writing [modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules).
+
+```js
+import a from './a'
+
+export { a }
+```
+
+Before ECMAScript Modules (ESM) became a standard (it took more than 10 years!), tooling like
+[webpack](https://webpack.js.org/guides/ecma-script-modules) and even languages like TypeScript started supporting so-called **ESM syntax**.
+However, there are some key differences with actual spec; here's [a helpful explainer](https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive).
+
+### What is 'Native' ESM?
+
+You may have been writing your app using ESM syntax for a long time. After all, it's natively supported by the browser, and in Nuxt 2 we compiled all the code you wrote to the appropriate format (CJS for server, ESM for browser).
+
+When adding modules to your package, things were a little different. A sample library might expose both CJS and ESM versions, and let us pick which one we wanted:
+
+```json
+{
+  "name": "sample-library",
+  "main": "dist/sample-library.cjs.js",
+  "module": "dist/sample-library.esm.js"
+}
+```
+
+So in Nuxt 2, the bundler (webpack) would pull in the CJS file ('main') for the server build and use the ESM file ('module') for the client build.
+
+However, in recent Node.js LTS releases, it is now possible to [use native ESM module](https://nodejs.org/api/esm.html) within Node.js. That means that Node.js itself can process JavaScript using ESM syntax, although it doesn't do it by default. The two most common ways to enable ESM syntax are:
+
+- set `"type": "module"` within your `package.json` and keep using `.js` extension
+- use the `.mjs` file extensions (recommended)
+
+This is what we do for Nuxt Nitro; we output a `.output/server/index.mjs` file. That tells Node.js to treat this file as a native ES module.
+
+### What Are Valid Imports in a Node.js Context?
+
+When you `import` a module rather than `require` it, Node.js resolves it differently. For example, when you import `sample-library`, Node.js will look not for the `main` but for the `exports` or `module` entry in that library's `package.json`.
+
+This is also true of dynamic imports, like `const b = await import('sample-library')`.
+
+Node supports the following kinds of imports (see [docs](https://nodejs.org/api/packages.html#determining-module-system)):
+
+1. files ending in `.mjs` - these are expected to use ESM syntax
+1. files ending in `.cjs` - these are expected to use CJS syntax
+1. files ending in `.js` - these are expected to use CJS syntax unless their `package.json` has `"type": "module"`
+
+### What Kinds of Problems Can There Be?
+
+For a long time module authors have been producing ESM-syntax builds but using conventions like `.esm.js` or `.es.js`, which they have added to the `module` field in their `package.json`. This hasn't been a problem until now because they have only been used by bundlers like webpack, which don't especially care about the file extension.
+
+However, if you try to import a package with an `.esm.js` file in a Node.js ESM context, it won't work, and you'll get an error like:
+
+```bash [Terminal]
+(node:22145) Warning: To load an ES module, set "type": "module" in the package.json or use the .mjs extension.
+/path/to/index.js:1
+
+export default {}
+^^^^^^
+
+SyntaxError: Unexpected token 'export'
+    at wrapSafe (internal/modules/cjs/loader.js:1001:16)
+    at Module._compile (internal/modules/cjs/loader.js:1049:27)
+    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1114:10)
+    ....
+    at async Object.loadESM (internal/process/esm_loader.js:68:5)
+```
+
+You might also get this error if you have a named import from an ESM-syntax build that Node.js thinks is CJS:
+
+```bash [Terminal]
+file:///path/to/index.mjs:5
+import { named } from 'sample-library'
+         ^^^^^
+SyntaxError: Named export 'named' not found. The requested module 'sample-library' is a CommonJS module, which may not support all module.exports as named exports.
+
+CommonJS modules can always be imported via the default export, for example using:
+
+import pkg from 'sample-library';
+const { named } = pkg;
+
+    at ModuleJob._instantiate (internal/modules/esm/module_job.js:120:21)
+    at async ModuleJob.run (internal/modules/esm/module_job.js:165:5)
+    at async Loader.import (internal/modules/esm/loader.js:177:24)
+    at async Object.loadESM (internal/process/esm_loader.js:68:5)
+```
+
+## Troubleshooting ESM Issues
+
+If you encounter these errors, the issue is almost certainly with the upstream library. They need to [fix their library](#library-author-guide) to support being imported by Node.
+
+### Transpiling Libraries
+
+In the meantime, you can tell Nuxt not to try to import these libraries by adding them to `build.transpile`:
+
+```ts twoslash
+export default defineNuxtConfig({
+  build: {
+    transpile: ['sample-library']
+  }
+})
+```
+
+You may find that you _also_ need to add other packages that are being imported by these libraries.
+
+### Aliasing Libraries
+
+In some cases, you may also need to manually alias the library to the CJS version, for example:
+
+```ts twoslash
+export default defineNuxtConfig({
+  alias: {
+    'sample-library': 'sample-library/dist/sample-library.cjs.js'
+  }
+})
+```
+
+### Default Exports
+
+A dependency with CommonJS format, can use `module.exports` or `exports` to provide a default export:
+
+```js [node_modules/cjs-pkg/index.js]
+module.exports = { test: 123 }
+// or
+exports.test = 123
+```
+
+This normally works well if we `require` such dependency:
+
+```js [test.cjs]
+const pkg = require('cjs-pkg')
+
+console.log(pkg) // { test: 123 }
+```
+
+[Node.js in native ESM mode](https://nodejs.org/api/esm.html#interoperability-with-commonjs), [typescript with `esModuleInterop` enabled](https://www.typescriptlang.org/tsconfig#esModuleInterop) and bundlers such as webpack, provide a compatibility mechanism so that we can default import such library.
+This mechanism is often referred to as "interop require default":
+
+```js
+import pkg from 'cjs-pkg'
+
+console.log(pkg) // { test: 123 }
+```
+
+However, because of the complexities of syntax detection and different bundle formats, there is always a chance that the interop default fails and we end up with something like this:
+
+```js
+import pkg from 'cjs-pkg'
+
+console.log(pkg) // { default: { test: 123 } }
+```
+
+Also when using dynamic import syntax (in both CJS and ESM files), we always have this situation:
+
+```js
+import('cjs-pkg').then(console.log) // [Module: null prototype] { default: { test: '123' } }
+```
+
+In this case, we need to manually interop the default export:
+
+```js
+// Static import
+import { default as pkg } from 'cjs-pkg'
+
+// Dynamic import
+import('cjs-pkg').then(m => m.default || m).then(console.log)
+```
+
+For handling more complex situations and more safety, we recommend and internally use [mlly](https://github.com/unjs/mlly) in Nuxt that can preserve named exports.
+
+```js
+import { interopDefault } from 'mlly'
+
+// Assuming the shape is { default: { foo: 'bar' }, baz: 'qux' }
+import myModule from 'my-module'
+
+console.log(interopDefault(myModule)) // { foo: 'bar', baz: 'qux' }
+```
+
+## Library Author Guide
+
+The good news is that it's relatively simple to fix issues of ESM compatibility. There are two main options:
+
+1. **You can rename your ESM files to end with `.mjs`.**
+
+   _This is the recommended and simplest approach._ You may have to sort out issues with your library's dependencies and possibly with your build system, but in most cases, this should fix the problem for you. It's also recommended to rename your CJS files to end with `.cjs`, for the greatest explicitness.
+
+1. **You can opt to make your entire library ESM-only**.
+
+   This would mean setting `"type": "module"` in your `package.json` and ensuring that your built library uses ESM syntax. However, you may face issues with your dependencies - and this approach means your library can _only_ be consumed in an ESM context.
+
+### Migration
+
+The initial step from CJS to ESM is updating any usage of `require` to use `import` instead:
+
+::code-group
+
+```js [Before]
+module.exports = ...
+
+exports.hello = ...
+```
+
+```js [After]
+export default ...
+
+export const hello = ...
+```
+
+::
+
+::code-group
+
+```js [Before]
+const myLib = require('my-lib')
+```
+
+```js [After]
+import myLib from 'my-lib'
+// or
+const myLib = await import('my-lib').then(lib => lib.default || lib)
+```
+
+::
+
+In ESM Modules, unlike CJS, `require`, `require.resolve`, `__filename` and `__dirname` globals are not available
+and should be replaced with `import()` and `import.meta.filename`.
+
+::code-group
+
+```js [Before]
+import { join } from 'path'
+
+const newDir = join(__dirname, 'new-dir')
+```
+
+```js [After]
+import { fileURLToPath } from 'node:url'
+
+const newDir = fileURLToPath(new URL('./new-dir', import.meta.url))
+```
+
+::
+
+::code-group
+
+```js [Before]
+const someFile = require.resolve('./lib/foo.js')
+```
+
+```js [After]
+import { resolvePath } from 'mlly'
+
+const someFile = await resolvePath('my-lib', { url: import.meta.url })
+```
+
+::
+
+### Best Practices
+
+- Prefer named exports rather than default export. This helps reduce CJS conflicts. (see [Default exports](#default-exports) section)
+
+- Avoid depending on Node.js built-ins and CommonJS or Node.js-only dependencies as much as possible to make your library usable in Browsers and Edge Workers without needing Nitro polyfills.
+
+- Use new `exports` field with conditional exports. ([read more](https://nodejs.org/api/packages.html#conditional-exports)).
+
+```json
+{
+  "exports": {
+    ".": {
+      "import": "./dist/mymodule.mjs"
+    }
+  }
+}
+```