@nuxt/docs-nightly 5.0.0-29741513.94de156f → 5.0.0-29741587.ad7d78f0

package/1.getting-started/05.assets.md

@@ -52,3 +52,129 @@ For example, referencing an image file that will be processed if a build tool is
 ::note
 Nuxt won't serve files in the [`app/assets/`](/docs/4.x/directory-structure/app/assets) directory at a static URL like `/assets/my-file.png`. If you need a static URL, use the [`public/`](/docs/4.x/getting-started/assets#public-directory) directory.
 ::
+
+### Static vs. Dynamic `src`
+
+When an `src` is a static string literal in your template, the build tool rewrites it into a runtime helper that resolves the final URL. A public path such as `/img/nuxt.png` is wrapped so that your [`app.baseURL`](/docs/4.x/api/nuxt-config#baseurl) is applied when the page renders, and a bundled path such as `~/assets/img/nuxt.png` additionally becomes an import that resolves to the hashed output file.
+
+```vue
+<template>
+  <!-- Static paths are rewritten: app.baseURL is applied at runtime, and the bundled file is hashed. -->
+  <img src="/img/nuxt.png">
+  <img src="~/assets/img/nuxt.png">
+</template>
+```
+
+Because `app.baseURL` is applied at runtime, a static public path works even when the base URL is only known at deploy time (for example set via `NUXT_APP_BASE_URL`), and it works whether or not the file is processed by the build. This resolution only happens for literal paths the build tool can see.
+
+A bound `:src` whose value is assembled at runtime is opaque to the build tool, so none of that rewriting happens. The string is used exactly as written:
+
+```vue
+<template>
+  <!-- This does not work: the path is built at runtime, so Vite never sees it as an import. -->
+  <img :src="`~/assets/img/${name}.png`">
+</template>
+```
+
+A runtime-built public path like `/img/${name}.png` is therefore **not** prefixed with [`app.baseURL`](/docs/4.x/api/nuxt-config#baseurl). If your application is deployed below the origin root, prefix it yourself with [`useRuntimeConfig().app.baseURL`](/docs/4.x/api/composables/use-runtime-config) (for example via [`joinURL`](https://github.com/unjs/ufo#joinurl)).
+
+The sections below cover how to handle each case when the path is only known at runtime.
+
+#### Public Assets
+
+If the files do not need to be processed or hashed, put them in the [`public/`](/docs/4.x/directory-structure/public) directory and reference them by URL:
+
+```vue [app/app.vue]
+<script setup lang="ts">
+const props = defineProps<{
+  name: string
+}>()
+
+const imageUrl = computed(() => `/img/${props.name}.png`)
+</script>
+
+<template>
+  <img
+    :src="imageUrl"
+    :alt="props.name"
+  >
+</template>
+```
+
+Files in `public/` keep their original filenames.
+
+#### Bundled Assets with Vite
+
+The approaches below are specific to Vite, Nuxt's default builder.
+
+When the possible files are known, list their imports explicitly:
+
+```vue [app/app.vue]
+<script setup lang="ts">
+const props = defineProps<{
+  theme: 'light' | 'dark'
+}>()
+
+const logos = {
+  light: () => import('./assets/img/logo-light.png?url'),
+  dark: () => import('./assets/img/logo-dark.png?url'),
+}
+
+const logoUrl = (await logos[props.theme]()).default
+</script>
+
+<template>
+  <img
+    :src="logoUrl"
+    alt="Nuxt"
+  >
+</template>
+```
+
+Each import has a literal path, so Vite can find both files at build time while loading only the selected module at runtime.
+
+When many files share a directory and extension, use a [variable dynamic import](https://vite.dev/guide/features.html#dynamic-import) instead of listing every file:
+
+```ts
+async function getImageUrl (name: string) {
+  const image = await import(`./assets/img/${name}.png?url`)
+  return image.default
+}
+```
+
+Only the filename can be dynamic in this example. Keeping the directory and extension in the import lets Vite find the possible files at build time.
+
+For a broader pattern or an explicit map of available files, use [`import.meta.glob`](https://vite.dev/guide/features.html#glob-import):
+
+```ts
+const images = import.meta.glob<string>('./assets/img/*.{png,jpg,svg}', {
+  query: '?url',
+  import: 'default',
+})
+
+async function getImageUrl (name: string) {
+  const load = images[`./assets/img/${name}.png`]
+
+  if (!load) {
+    throw new Error(`Unknown image: ${name}`)
+  }
+
+  return await load()
+}
+```
+
+Glob imports are lazy by default. Add `eager: true` if the URLs must be available synchronously:
+
+```ts
+const images = import.meta.glob<string>('./assets/img/*.{png,jpg,svg}', {
+  query: '?url',
+  import: 'default',
+  eager: true,
+})
+```
+
+Every matching asset is still included in the build output. Lazy imports load each match on demand, while an eager glob loads all matches up front and can increase the initial JavaScript size or inline small assets.
+
+::warning
+Await a lazy import before using its URL in server-rendered markup. Vite's [`new URL(..., import.meta.url)` pattern](https://vite.dev/guide/assets.html#new-url-url-import-meta-url) does not work with SSR.
+::

package/3.guide/4.modules/7.best-practices.md

@@ -41,7 +41,7 @@ When your module needs to perform one-time setup tasks (like generating configur
 
 ```ts
 import { addServerHandler, defineNuxtModule } from 'nuxt/kit'
-import semver from 'semver'
+import { isLess } from 'verkit'
 
 export default defineNuxtModule({
   meta: {
@@ -54,7 +54,7 @@ export default defineNuxtModule({
   },
   async onUpgrade (nuxt, options, previousVersion) {
     // Handle version-specific migrations
-    if (semver.lt(previousVersion, '1.0.0')) {
+    if (isLess(previousVersion, '1.0.0')) {
       await migrateLegacyData()
     }
   },

package/3.guide/6.going-further/10.runtime-config.md

@@ -61,6 +61,10 @@ Setting the default of `runtimeConfig` values to *differently named environment
 It is advised to use environment variables that match the structure of your `runtimeConfig` object.
 ::
 
+::warning
+Environment variable values are automatically cast to their JavaScript type using [`destr`](https://github.com/unjs/destr). For example, `NUXT_MY_VAR=4848e0` becomes the number `4848`. To keep a value a string, the environment variable value itself must contain literal double quotes: in a `.env` file, write `NUXT_MY_VAR='"4848e0"'`; when setting the variable directly (in a shell, Dockerfile, or hosting dashboard), make sure the quotes are part of the value and not stripped by the shell (for example `NUXT_MY_VAR='"4848e0"' node .output/server/index.mjs`).
+::
+
 ::tip{icon="i-lucide-video" to="https://youtu.be/_FYV5WfiWvs" target="_blank"}
 Watch a video from Alexander Lichter showcasing the top mistake developers make using runtimeConfig.
 ::

package/4.api/5.kit/1.modules.md

@@ -205,7 +205,7 @@ Lifecycle hooks run before the main `setup` function, and if a hook throws an er
 
 ```ts
 import { defineNuxtModule } from '@nuxt/kit'
-import semver from 'semver'
+import { isLess } from 'verkit'
 
 export default defineNuxtModule({
   meta: {
@@ -239,7 +239,7 @@ export default defineNuxtModule({
     // - Clean up deprecated files
     // - Display upgrade notes
 
-    if (semver.lt(previousVersion, '1.1.0')) {
+    if (isLess(previousVersion, '1.1.0')) {
       console.log('⚠️  Breaking changes in 1.1.0 - please check the migration guide')
     }
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "5.0.0-29741513.94de156f",
+  "version": "5.0.0-29741587.ad7d78f0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",