@nuxt/docs 4.1.2 → 4.2.0

package/2.guide/{1.concepts → 2.concepts}/7.esm.md

@@ -32,7 +32,7 @@ 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).
+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?
 
@@ -50,6 +50,10 @@ When adding modules to your package, things were a little different. A sample li
 
 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.
 
+::note
+The `module` field is a convention used by bundlers like webpack and Rollup, but is not recognized by Node.js itself. Node.js only uses the [`exports`](https://nodejs.org/api/packages.html#exports) and [`main`](https://nodejs.org/api/packages.html#main) fields for module resolution.
+::
+
 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
@@ -59,7 +63,7 @@ This is what we do for Nuxt Nitro; we output a `.output/server/index.mjs` file.
 
 ### 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`.
+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 for the `exports` entry in that library's `package.json`, or fall back to the `main` entry if `exports` is not defined.
 
 This is also true of dynamic imports, like `const b = await import('sample-library')`.
 
@@ -111,7 +115,7 @@ const { named } = pkg;
 
 ## 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.
+If you encounter these errors, the issue is almost certainly with the upstream library. They need to [fix their library](/docs/4.x/guide/concepts/esm#library-author-guide) to support being imported by Node.
 
 ### Transpiling Libraries
 
@@ -120,8 +124,8 @@ In the meantime, you can tell Nuxt not to try to import these libraries by addin
 ```ts twoslash
 export default defineNuxtConfig({
   build: {
-    transpile: ['sample-library']
-  }
+    transpile: ['sample-library'],
+  },
 })
 ```
 
@@ -134,8 +138,8 @@ In some cases, you may also need to manually alias the library to the CJS versio
 ```ts twoslash
 export default defineNuxtConfig({
   alias: {
-    'sample-library': 'sample-library/dist/sample-library.cjs.js'
-  }
+    'sample-library': 'sample-library/dist/sample-library.cjs.js',
+  },
 })
 ```
 
@@ -182,6 +186,8 @@ import('cjs-pkg').then(console.log) // [Module: null prototype] { default: { tes
 
 In this case, we need to manually interop the default export:
 
+<!-- eslint-disable import/no-named-default -->
+
 ```js
 // Static import
 import { default as pkg } from 'cjs-pkg'
@@ -219,16 +225,16 @@ The initial step from CJS to ESM is updating any usage of `require` to use `impo
 
 ::code-group
 
-```js [Before]
-module.exports = ...
+```ts [Before]
+module.exports = function () { /* ... */ }
 
-exports.hello = ...
+exports.hello = 'world'
 ```
 
-```js [After]
-export default ...
+```ts [After]
+export default function () { /* ... */ }
 
-export const hello = ...
+export const hello = 'world'
 ```
 
 ::
@@ -242,7 +248,7 @@ const myLib = require('my-lib')
 ```js [After]
 import myLib from 'my-lib'
 // or
-const myLib = await import('my-lib').then(lib => lib.default || lib)
+const dynamicMyLib = await import('my-lib').then(lib => lib.default || lib)
 ```
 
 ::
@@ -253,7 +259,7 @@ and should be replaced with `import()` and `import.meta.filename`.
 ::code-group
 
 ```js [Before]
-import { join } from 'path'
+const { join } = require('node:path')
 
 const newDir = join(__dirname, 'new-dir')
 ```
@@ -282,7 +288,7 @@ 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)
+- Prefer named exports rather than default export. This helps reduce CJS conflicts. (see [Default exports](/docs/4.x/guide/concepts/esm#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.
 

package/2.guide/{1.concepts → 2.concepts}/8.typescript.md

@@ -5,7 +5,7 @@ description: "Nuxt is fully typed and provides helpful shortcuts to ensure you h
 
 ## Type-checking
 
-By default, Nuxt doesn't check types when you run [`nuxt dev`](/docs/api/commands/dev) or [`nuxt build`](/docs/api/commands/build), for performance reasons.
+By default, Nuxt doesn't check types when you run [`nuxt dev`](/docs/4.x/api/commands/dev) or [`nuxt build`](/docs/4.x/api/commands/build), for performance reasons.
 
 To enable type-checking at build or development time, install `vue-tsc` and `typescript` as development dependency:
 
@@ -29,19 +29,19 @@ To enable type-checking at build or development time, install `vue-tsc` and `typ
 
 ::
 
-Then, run [`nuxt typecheck`](/docs/api/commands/typecheck) command to check your types:
+Then, run [`nuxt typecheck`](/docs/4.x/api/commands/typecheck) command to check your types:
 
 ```bash [Terminal]
 npx nuxt typecheck
 ```
 
-To enable type-checking at build or development time, you can also use the [`typescript.typeCheck`](/docs/api/nuxt-config#typecheck) option in your `nuxt.config` file:
+To enable type-checking at build or development time, you can also use the [`typescript.typeCheck`](/docs/4.x/api/nuxt-config#typecheck) option in your `nuxt.config` file:
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   typescript: {
-    typeCheck: true
-  }
+    typeCheck: true,
+  },
 })
 ```
 
@@ -60,25 +60,25 @@ Some of the references in the file are to files that are only generated within y
 This file contains the recommended basic TypeScript configuration for your project, including resolved aliases injected by Nuxt or modules you are using, so you can get full type support and path auto-complete for aliases like `~/file` or `#build/file`.
 
 ::note
-Consider using the `imports` section of [nuxt.config](/docs/api/nuxt-config#imports) to include directories beyond the default ones. This can be useful for auto-importing types which you're using across your app.
+Consider using the `imports` section of [nuxt.config](/docs/4.x/api/nuxt-config#imports) to include directories beyond the default ones. This can be useful for auto-importing types which you're using across your app.
 ::
 
-[Read more about how to extend this configuration](/docs/guide/directory-structure/tsconfig).
+[Read more about how to extend this configuration](/docs/4.x/guide/directory-structure/tsconfig).
 
 ::tip{icon="i-lucide-video" to="https://youtu.be/umLI7SlPygY" target="_blank"}
 Watch a video from Daniel Roe explaining built-in Nuxt aliases.
 ::
 
 ::note
-Nitro also [auto-generates types](/docs/guide/concepts/server-engine#typed-api-routes) for API routes. Plus, Nuxt also generates types for globally available components and [auto-imports from your composables](/docs/guide/directory-structure/app/composables), plus other core functionality.
+Nitro also [auto-generates types](/docs/4.x/guide/concepts/server-engine#typed-api-routes) for API routes. Plus, Nuxt also generates types for globally available components and [auto-imports from your composables](/docs/4.x/guide/directory-structure/app/composables), plus other core functionality.
 ::
 
 ::note
-For backward compatibility, Nuxt still generates `./.nuxt/tsconfig.json`. However, we recommend using [TypeScript project references](/docs/guide/directory-structure/tsconfig) with the new configuration files (`.nuxt/tsconfig.app.json`, `.nuxt/tsconfig.server.json`, etc.) for better type safety and performance.
+For backward compatibility, Nuxt still generates `./.nuxt/tsconfig.json`. However, we recommend using [TypeScript project references](/docs/4.x/guide/directory-structure/tsconfig) with the new configuration files (`.nuxt/tsconfig.app.json`, `.nuxt/tsconfig.server.json`, etc.) for better type safety and performance.
 
 If you do extend from `./.nuxt/tsconfig.json`, keep in mind that all options will be overwritten by those defined in your `tsconfig.json`. Overwriting options such as `"compilerOptions.paths"` with your own configuration will lead TypeScript to not factor in the module resolutions, which can cause module resolutions such as `#imports` to not be recognized.
 
-In case you need to extend options further, you can use the [`alias` property](/docs/api/nuxt-config#alias) within your `nuxt.config`. Nuxt will pick them up and extend the generated TypeScript configurations accordingly.
+In case you need to extend options further, you can use the [`alias` property](/docs/4.x/api/nuxt-config#alias) within your `nuxt.config`. Nuxt will pick them up and extend the generated TypeScript configurations accordingly.
 ::
 
 ## Project References
@@ -133,7 +133,7 @@ If you are currently converting your codebase to TypeScript, you may want to tem
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   typescript: {
-    strict: false
-  }
+    strict: false,
+  },
 })
 ```

package/2.guide/3.going-further/1.events.md

@@ -16,7 +16,7 @@ You can create your own custom events using the `hook` method:
 ```ts
 const nuxtApp = useNuxtApp()
 
-nuxtApp.hook('app:user:registered', payload => {
+nuxtApp.hook('app:user:registered', (payload) => {
   console.log('A new user has registered!', payload)
 })
 ```
@@ -37,7 +37,7 @@ You can also use the payload object to enable two-way communication between the
 ```ts
 const nuxtApp = useNuxtApp()
 
-nuxtApp.hook('app:user:registered', payload => {
+nuxtApp.hook('app:user:registered', (payload) => {
   payload.message = 'Welcome to our app!'
 })
 
@@ -58,6 +58,6 @@ await nuxtApp.callHook('app:user:registered', {
 You can inspect all events using the **Nuxt DevTools** Hooks panel.
 ::
 
-::read-more{to="/docs/guide/going-further/hooks"}
+::read-more{to="/docs/4.x/guide/going-further/hooks"}
 Learn more about Nuxt's built-in hooks and how to extend them
 ::