Proposal: Try to clarify CDN vs ESM in the examples

[skirtles-code]

The Problem

In Vue 2, the difference between using a CDN build and an ESM module was pretty small:

import Vue from 'vue'

new Vue({})

The only difference is that first line, which can be removed for a CDN build.

From a documentation perspective, this similarity was really convenient as the examples could largely ignore which build was being used.

In Vue 3 we have a larger difference:

// ESM
import { createApp } from 'vue'

createApp({})

// CDN
Vue.createApp({})

Most of the documentation uses this second style, prefixing everything with Vue.. While this isn't wrong, I've noticed that beginners seem to be getting confused by this. In practice, many of them are using SFCs and aren't sure how to convert the examples across.

More generally, the differences between the ESM and CDN builds aren't really explained anywhere. While these differences are common to many other libraries it isn't safe to assume that all readers are going to be familiar with these conventions. A lot of readers will only really be familiar with their one work project and so only have exposure to either ESM or CDN but not both.

Proposed Solution

I have three suggestions.

On the Installation page it should explicitly mention that the CDN build exposes a global Vue object with properties equivalent to those imported via an ESM build. There is currently a small mention of this in the section Explanation of Different Builds but I don't think it really explains it clearly and I'd imagine most newcomers are going to skip over that section. Whilst fully rewriting that section isn't my intention, it would perhaps be a viable alternative.

My second suggestion is to make some acknowledgement of the difference near the start of the Introduction page. It doesn't need to be much, just something to clarify that the examples are assuming a CDN build and how it'd be slightly different for ESM (it needs an example, people skim text without code). Possibly something at the end of the Getting Started section, just after it talks about using Vue CLI.

My third suggestion is the biggest change. I think we should rewrite several of the examples to use destructuring so that they are almost equivalent to using ESM. Consider the example I gave earlier:

// CDN
Vue.createApp({})

We could instead write it as:

const { createApp } = Vue

createApp({})

In that form it looks almost the same as an ESM example. Only the first line is different, everything else would be the same.

Once the early examples have established the convention of destructuring global APIs out of the global Vue, subsequent examples can drop that line altogether. Those examples would then be interchangeable between CDN and ESM.

Next Steps

The third change would likely be quite large, so I'd like to get preliminary approval for the idea before embarking on that change. It'd also need some of the CodePen examples to be changed, so I couldn't do this single-handedly.

[NataliaTepluhina]

@skirtles-code I think the third one while being large, is also the most preferable. For the first several examples we could also add more verbosity:

// for CDN build
const { createApp } = Vue

// or, if you are using ESM
import { createApp } from 'vue'

createApp({})

What do you think?

P.S. In the perfect world, I would probably rewrite everything to SFC syntax but this idea was opposed when we discussed it before starting Vue 3 documentation

[skirtles-code]

I'm going to break this down into multiple PRs, there are too many examples to change them all in one go.

I agree that some of the earlier pages should mention both styles. I'll need to be careful though as it could prove a distraction from whatever topic is being discussed.

[NataliaTepluhina]

Closing this one as we have an API switcher in the new docs, so the examples shouldn't be universal anymore