3.1 Updates

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 }`
@@ -113,7 +92,7 @@ const app = createApp({
   }
 })
 
-app.config.optionMergeStrategies.hello = (parent, child, vm) => {
+app.config.optionMergeStrategies.hello = (parent, child) => {
   return `Hello, ${child}`
 }
 
@@ -126,7 +105,7 @@ app.mixin({
 
 Define merging strategies for custom options.
 
-The merge strategy receives the value of that option defined on the parent and child instances as the first and second arguments, respectively. The context application instance is passed as the third argument.
+The merge strategy receives the value of that option defined on the parent and child instances as the first and second arguments, respectively.
 
 - **See also:** [Custom Option Merging Strategies](../guide/mixins.html#custom-option-merge-strategies)
 
@@ -139,3 +118,91 @@ 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 affect 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 contain newlines are removed
+3. Consecutive whitespaces in text nodes are condensed into a single space
+
+Setting the value to `'preserve'` will disable (2) and (3).
+
+### compilerOptions.delimiters
+
+- **Type:** `Array<string>`
+
+- **Default:** `{{ "['\u007b\u007b', '\u007d\u007d']" }}`
+
+- **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 option 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/composition-api.md

@@ -4,32 +4,51 @@
 
 ## `setup`
 
-A component option that is executed **before** the component is created, once the `props` are resolved, and serves as the entry point for composition API's
+A component option that is executed **before** the component is created, once the `props` are resolved. It serves as the entry point for composition APIs.
 
 - **Arguments:**
 
   - `{Data} props`
   - `{SetupContext} context`
 
+  Similar to `this.$props` when using Options API, the `props` object will only contain explicitly declared props. Also, all declared prop keys will be present on the `props` object, regardless of whether it was passed by the parent component or not. Absent optional props will have a value of `undefined`.
+
+  If you need to check the absence of an optional prop, you can give it a Symbol as its default value:
+
+  ```js
+  const isAbsent = Symbol()
+
+  export default {
+    props: {
+      foo: { default: isAbsent }
+    },
+    setup(props) {
+      if (props.foo === isAbsent) {
+        // foo was not provided.
+      }
+    }
+  }
+  ```
+
 - **Typing**:
 
-```ts
-interface Data {
-  [key: string]: unknown
-}
+  ```ts
+  interface Data {
+    [key: string]: unknown
+  }
 
-interface SetupContext {
-  attrs: Data
-  slots: Slots
-  emit: (event: string, ...args: unknown[]) => void
-}
+  interface SetupContext {
+    attrs: Data
+    slots: Slots
+    emit: (event: string, ...args: unknown[]) => void
+  }
 
-function setup(props: Data, context: SetupContext): Data
-```
+  function setup(props: Data, context: SetupContext): Data
+  ```
 
-::: tip
-To get type inference for the arguments passed to `setup()`, the use of [defineComponent](global-api.html#definecomponent) is needed.
-:::
+  ::: tip
+  To get type inference for the arguments passed to `setup()`, the use of [defineComponent](global-api.html#definecomponent) is needed.
+  :::
 
 - **Example**
 
@@ -129,48 +148,52 @@ The component instance context is also set during the synchronous execution of l
 
 - **Typing**:
 
-```ts
-interface InjectionKey<T> extends Symbol {}
-
-function provide<T>(key: InjectionKey<T> | string, value: T): void
-
-// without default value
-function inject<T>(key: InjectionKey<T> | string): T | undefined
-// with default value
-function inject<T>(key: InjectionKey<T> | string, defaultValue: T): T
-// with factory
-function inject<T>(
-  key: InjectionKey<T> | string,
-  defaultValue: () => T,
-  treatDefaultAsFactory: true
-): T
-```
+  ```ts
+  interface InjectionKey<T> extends Symbol {}
+
+  function provide<T>(key: InjectionKey<T> | string, value: T): void
+
+  // without default value
+  function inject<T>(key: InjectionKey<T> | string): T | undefined
+  // with default value
+  function inject<T>(key: InjectionKey<T> | string, defaultValue: T): T
+  // with factory
+  function inject<T>(
+    key: InjectionKey<T> | string,
+    defaultValue: () => T,
+    treatDefaultAsFactory: true
+  ): T
+  ```
 
-Vue provides an `InjectionKey` interface which is a generic type that extends `Symbol`. It can be used to sync the type of the injected value between the provider and the consumer:
+  Vue provides an `InjectionKey` interface which is a generic type that extends `Symbol`. It can be used to sync the type of the injected value between the provider and the consumer:
 
-```ts
-import { InjectionKey, provide, inject } from 'vue'
+  ```ts
+  import { InjectionKey, provide, inject } from 'vue'
 
-const key: InjectionKey<string> = Symbol()
+  const key: InjectionKey<string> = Symbol()
 
-provide(key, 'foo') // providing non-string value will result in error
+  provide(key, 'foo') // providing non-string value will result in error
 
-const foo = inject(key) // type of foo: string | undefined
-```
+  const foo = inject(key) // type of foo: string | undefined
+  ```
 
-If using string keys or non-typed symbols, the type of the injected value will need to be explicitly declared:
+  If using string keys or non-typed symbols, the type of the injected value will need to be explicitly declared:
 
-```ts
-const foo = inject<string>('foo') // string | undefined
-```
+  ```ts
+  const foo = inject<string>('foo') // string | undefined
+  ```
 
 - **See also**:
   - [Provide / Inject](../guide/component-provide-inject.html)
   - [Composition API Provide / Inject](../guide/composition-api-provide-inject.html)
 
 ## `getCurrentInstance`
 
-`getCurrentInstance` enables access to an internal component instance useful for advanced usages or for library creators.
+`getCurrentInstance` enables access to an internal component instance.
+
+:::warning
+`getCurrentInstance` is only exposed for advanced use cases, typically in libraries. Usage of `getCurrentInstance` is strongly discouraged in application code. Do **NOT** use it as an escape hatch to get the equivalent of `this` in Composition API.
+:::
 
 ```ts
 import { getCurrentInstance } from 'vue'

src/api/directives.md

@@ -454,31 +454,6 @@
 - **See also:**
   - [Data Binding Syntax - interpolations](../guide/template-syntax.html#text)
 
-## v-is
+## v-is <Badge text="deprecated" type="warning" />
 
-> Note: this section only affects cases where Vue templates are directly written in the page's HTML.
-
-- **Expects:** string literal
-
-- **Limited to:** native HTML elements
-
-- **Usage:** When using in-DOM templates, the template is subject to native HTML parsing rules. Some HTML elements, such as `<ul>`, `<ol>`, `<table>` and `<select>` have restrictions on what elements can appear inside them, and some elements such as `<li>`, `<tr>`, and `<option>` can only appear inside certain other elements. As a workaround, we can use `v-is` directive on these elements:
-
-```html
-<table>
-  <tr v-is="'blog-post-row'"></tr>
-</table>
-```
-
-:::warning
-`v-is` functions like a dynamic 2.x `:is` binding - so to render a component by its registered name, its value should be a JavaScript string literal:
-
-```html
-<!-- Incorrect, nothing will be rendered -->
-<tr v-is="blog-post-row"></tr>
-
-<!-- Correct -->
-<tr v-is="'blog-post-row'"></tr>
-```
-
-:::
+Deprecated in 3.1.0. Use [`is` attribute with `vue:` prefix](/api/special-attributes.html#is) 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.