Add docs for --legacy flag

[benmccann]

Sending this based off the discussion in #1206

Closes #876
Closes #739

This isn't really the whole story for legacy browser support, but it's a good start. I think a lot of the docs for cross-browser support should go in the Svelte docs, which is why I didn't try to add more here yet.

Questions I have:

• Does Sapper do anything special or is this a straight pass-through to Svelte's --legacy option?
• Should we mention that a legacy browser is one that doesn't support async? (docs: improve legacy flag description #1206 (comment)). I think it'd be useful for people to know exactly which browsers are in each bundle. Where's the code that does this?

[antony]

Might need a bit more detail

[antony]

Should we mention that a legacy browser is one that doesn't support async? (#1206 (comment)). I think it'd be useful for people to know exactly which browsers are in each bundle. Where's the code that does this?

Can't answer your first question, but there isn't a comprehensive list of browsers that are / aren't supported. The check does indeed just use an async/await test, which might not be ideal

[antony]

How do people feel about being slightly more explicit like this?

[Conduitry]

I'm trying to weigh the benefits of saying something more generally helpful here vs saying something more technically correct. What the --legacy flag actually does to your build is entirely in the user's hands by way of what they have in their rollup.config.js. The default sapper-template currently happens to swap in a given Babel configuration when building in legacy mode, but this is not set in stone and this is not truly Sapper's responsibility.

The more correct thing to say here would be that --legacy makes Sapper create two builds, with differing values of a given build-time environment variable, and serves one or the other depending on async/await support. Users can have this environment variable affect whatever they want in their Rollup config. I don't know how to convey all of this in a way that is correct and useful and unintimidating.

[benmccann]

I think that's a really helpful callout and we should definitely mention something about the flag being passed to the bundler.

How does Sapper's legacy option interact with Svelte's legacy option? I assumed that if you specified legacy in Sapper that it would pass it to Svelte which was the main effect. But looking at the code I'm not sure it does get passed unless I'm missing where it happens?

[Conduitry]

I don't believe legacy in Sapper is passed along to legacy in Svelte. Svelte's legacy flag is for avoiding generating code that doesn't transpile or polyfill well back to IE9-ish. Sapper's legacy build is (more or less) delivered to all versions of IE.

You'd probably have an awful time getting a Sapper app to run on versions of IE before 11 anyway, and legacy in Svelte isn't needed for IE11, so I don't think changing this default makes sense. (But, if someone wanted to, they could again do in in their bundler config, as this is not up to Sapper.)

[benmccann]

Ok, I took a stab at incorporating this additional information

[antony]

This works for me - would've been very useful at the time!

[pngwn]

Lets add an additional note to this that the legacy build defined in the template's rollup config is just an example, and that users can tweak it to fit their requirements. The current wording suggest that this should 'just work' which may be true in some cases but is definitely false in others.