From 32c75e26d6f792a7fb31ba198c0b384efd8ffb66 Mon Sep 17 00:00:00 2001
From: Bjorn Lu <bjornlu.dev@gmail.com>
Date: Mon, 16 May 2022 00:59:08 +0800
Subject: [PATCH] docs(plugin-vue): clarify asset url handling (#8184)

---
 packages/plugin-vue/README.md | 43 ++++++++++++++++++++++++++++-------
 1 file changed, 35 insertions(+), 8 deletions(-)

diff --git a/packages/plugin-vue/README.md b/packages/plugin-vue/README.md
index a232982e8aed59..ae848051cecd10 100644
--- a/packages/plugin-vue/README.md
+++ b/packages/plugin-vue/README.md
@@ -51,6 +51,40 @@ export interface Options {
 }
 ```
 
+## Asset URL handling
+
+When `@vitejs/plugin-vue` compiles the `<template>` blocks in SFCs, it also converts any encountered asset URLs into ESM imports.
+
+For example, the following template snippet:
+
+```vue
+<img src="../image.png" />
+```
+
+Is the same as:
+
+```vue
+<script setup>
+import _imports_0 from '../image.png'
+</script>
+
+<img src="_imports_0" />
+```
+
+By default the following tag/attribute combinations are transformed, and can be configured using the `template.transformAssetUrls` option.
+
+```js
+{
+  video: ['src', 'poster'],
+  source: ['src'],
+  img: ['src'],
+  image: ['xlink:href', 'href'],
+  use: ['xlink:href', 'href']
+}
+```
+
+Note that only attribute values that are static strings are transformed. Otherwise, you'd need to import the asset manually, e.g. `import imgUrl from '../image.png'`.
+
 ## Example for passing options to `vue/compiler-sfc`:
 
 ```ts
@@ -64,14 +98,7 @@ export default {
           // ...
         },
         transformAssetUrls: {
-          // default tags
-          tags: {
-            video: ['src', 'poster'],
-            source: ['src'],
-            img: ['src'],
-            image: ['xlink:href', 'href'],
-            use: ['xlink:href', 'href']
-          }
+          // ...
         }
       }
     })