feat: document 3.1 compilerOptions

Author: yyx990803

src/api/application-config.md

@@ -77,27 +77,6 @@ const app = createApp({})
 app.config.globalProperties.$http = () => {}
 ```
 
-## isCustomElement
-
-- **Type:** `(tag: string) => boolean`
-
-- **Default:** `undefined`
-
-- **Usage:**
-
-```js
-// any element starting with 'ion-' will be recognized as a custom one
-app.config.isCustomElement = tag => tag.startsWith('ion-')
-```
-
-Specifies a method to recognize custom elements defined outside of Vue (e.g., using the Web Components APIs). If component matches this condition, it won't need local or global registration and Vue won't throw a warning about an `Unknown custom element`.
-
-> Note that all native HTML and SVG tags don't need to be matched in this function - Vue parser performs this check automatically
-
-::: tip Important
-This config option is only respected when using the runtime compiler. If you are using the runtime-only build, `isCustomElement` must be passed to `@vue/compiler-dom` in the build setup instead - for example, via the [`compilerOptions` option in vue-loader](https://vue-loader.vuejs.org/options.html#compileroptions).
-:::
-
 ## optionMergeStrategies
 
 - **Type:** `{ [key: string]: Function }`
@@ -139,3 +118,93 @@ The merge strategy receives the value of that option defined on the parent and c
 - **Usage**:
 
 Set this to `true` to enable component init, compile, render and patch performance tracing in the browser devtool performance/timeline panel. Only works in development mode and in browsers that support the [performance.mark](https://developer.mozilla.org/en-US/docs/Web/API/Performance/mark) API.
+
+## compilerOptions <Badge text="3.1+" />
+
+- **Type:** `Object`
+
+Configure runtime compiler options. Values set on this object will be passed to the in-browser template compiler and affects every component in the configured app. Note you can also override these options on a per-component basis using the [`compilerOptions` option](/api/options-misc.html#compileroptions).
+
+::: tip Important
+This config option is only respected when using the full build (i.e. the standalone `vue.js` that can compile templates in the browser). If you are using the runtime-only build with a build setup, compiler options must be passed to `@vue/compiler-dom` via build tool configurations instead.
+
+- For `vue-loader`: [pass via the `compilerOptions` loader option](https://vue-loader.vuejs.org/options.html#compileroptions). Also see [how to configure it in `vue-cli`](https://cli.vuejs.org/guide/webpack.html#modifying-options-of-a-loader).
+
+- For `vite`: [pass via `@vitejs/plugin-vue` options](https://github.com/vitejs/vite/tree/main/packages/plugin-vue#example-for-passing-options-to-vuecompiler-dom).
+  :::
+
+### compilerOptions.isCustomElement
+
+- **Type:** `(tag: string) => boolean`
+
+- **Default:** `undefined`
+
+- **Usage:**
+
+```js
+// any element starting with 'ion-' will be recognized as a custom one
+app.config.compilerOptions.isCustomElement = tag => tag.startsWith('ion-')
+```
+
+Specifies a method to recognize custom elements defined outside of Vue (e.g., using the Web Components APIs). If component matches this condition, it won't need local or global registration and Vue won't throw a warning about an `Unknown custom element`.
+
+> Note that all native HTML and SVG tags don't need to be matched in this function - Vue parser performs this check automatically.
+
+### compilerOptions.whitespace
+
+- **Type:** `'condense' | 'preserve'`
+
+- **Default:** `'condense'`
+
+- **Usage:**
+
+```js
+app.config.compilerOptions.whitespace = 'preserve'
+```
+
+By default, Vue removes/condenses whitespaces between template elements to produce more efficient compiled output:
+
+1. Leading / ending whitespaces inside an element are condensed into a single space
+2. Whitespaces between elements that contains newlines are removed
+3. Consecutive whitepsaces in text nodes are condensed into a single space
+
+Setting the value to `'preserve'` will disalbe (2) and (3).
+
+### compilerOptions.delimiters
+
+- **Type:** `Array<string>`
+
+- **Default:** `{{ "['\u007b\u007b', '\u007d\u007d']" }}`
+
+- **Restrictions:** This option is only available in the full build, with in-browser template compilation.
+
+- **Usage:**
+
+```js
+// Delimiters changed to ES6 template string style
+app.config.compilerOptions.delimiters = ['${', '}']    
+```
+
+Sets the delimiters used for text interpolation within the template.
+
+Typically this is used to avoid conflicting with server-side frameworks that also use mustache syntax.
+
+### compilerOptions.comments
+
+- **Type:** `boolean`
+
+- **Default:** `false`
+
+- **Usage:**
+
+```js
+app.config.compilerOptions.comments = true
+```
+
+By default, Vue will remove HTML comments inside templates in production. Setting this option to `true` will force Vue to preserve comments even in production. Comments are always preserved during development.
+
+This options is typically used when Vue is used with other libraries that rely on HTML comments.
+
+## isCustomElement <Badge text="deprecated" type="warning"/>
+
+Deprecated in 3.1.0. Use [`compilerOptions.isCustomElement`](#compileroptions-iscustomelement) instead.

src/api/options-misc.md

@@ -10,29 +10,6 @@
 
   Another benefit of specifying a `name` option is debugging. Named components result in more helpful warning messages. Also, when inspecting an app in the [vue-devtools](https://github.com/vuejs/vue-devtools), unnamed components will show up as `<AnonymousComponent>`, which isn't very informative. By providing the `name` option, you will get a much more informative component tree.
 
-## delimiters
-
-- **Type:** `Array<string>`
-
-- **Default:** `{{ "['\u007b\u007b', '\u007d\u007d']" }}` 
-
-- **Restrictions:** This option is only available in the full build, with in-browser template compilation.
-
-- **Details:**
-
-  Sets the delimiters used for text interpolation within the template.
-
-  Typically this is used to avoid conflicting with server-side frameworks that also use mustache syntax.
-
-- **Example:**
-
-  ```js
-  createApp({
-    // Delimiters changed to ES6 template string style
-    delimiters: ['${', '}']
-  })
-  ```
-
 ## inheritAttrs
 
 - **Type:** `boolean`
@@ -64,3 +41,31 @@
   ```
 
 - **See also:** [Disabling Attribute Inheritance](../guide/component-attrs.html#disabling-attribute-inheritance)
+
+## compilerOptions <Badge text="3.1+" />
+
+- **Type:** `Object`
+
+- **Details:**
+
+  This is the component-level equivalent of the [app-level `compilerOptions` config](/api/application-config.html#compileroptions).
+
+- **Usage:**
+
+  ```js
+  const Foo = {
+    // ...
+    compilerOptions: {
+      delimiters: ['${', '}'],
+      comments: true
+    }
+  }
+  ```
+
+  ::: tip Important
+  Similar to the app-level `compilerOptions` config, this option is only respected when using the full build with in-browser template compilation.
+  :::
+
+## delimiters <Badge text="deprecated" type="warning" />
+
+Deprecated in 3.1.0. Use `compilerOptions.delimiters` instead.