feat: legacy JS support

[Tal500]

Brief

A feature-complete zero-configuration (JS output) legacy support of SvelteKit, by being compatible with the (potential) output of @vitejs/plugin-legacy. Additionally, it applies legacy configurations and fixes some JS compatibility issues of kit.svelte.dev with legacy browser, so the official website wouldn't be totally unsupported by legacy browsers.

Online Demo

Please test in your legacy browsers and share the experience/bugs you have.

Def: legacy browser := any browser that doesn't fully supports the ES modules. (according to the vite legacy plugin)

closes #12 (Initiated by and) an alternative to #2745 A more robust alternative to PR #5417, thought I didn't cancel here the introduced changes by this external PR. Probably closes the old sveltejs/svelte#3388.

Manual Testing

On the simple demo & the kit.svelte.dev website that will be described later:

• IE11 - Works well (except minor styling issues in the simple demo, but bigger ones in kit.svelte.dev)
• Chrome 15 (yes, that's old) - Works assuming you're willing to give up on the following Svelte features:
  • svelte/animation - The flip animation requires that the style will have the property transformOrigin, which isn't suppported (see caniuseit. We can try to patch Svelte to use webkit- prefix, but is it worth it?)
  • svelte/transition - For some reason I have encountered some "DOM Exception type 12" errors, don't know (and not sure I want to know) how to fix it except not using transitions at all.
  • svelte/motion - Before chrome 24, there is no support both for window.requestanimationframe() and window.performance.now(). There are polyfills for both of them, but the latter use the precision of Date.now() that is awful (for example the counter component on the simple demo uses svelte/motion.spring, and because the precision it's jumping crazy). For reference, the two polyfills are available here and here (the second one is actually ponyfill, meaning you'll need to overwrite window.performance to be the value of the exported object there by yourself, see the manual there).

I would like that other people here test the following demos on their machines and share their experience.

Demo

Notice: both of the demos are using postcss-preset-env for a limited support of CSS variables in legacy browsers.

Simple

A simple demo is available at this repository, together with an online preview in cloudflare pages (the same demo in the brief section). This demo also include some "patched css" to avoid forcing using CSS variables, when there isn't support, and additionally define and uses some polyfills. After cloning, to run the demo, execute pnpm install && pnpm build && pnpm preview, and you can see the results both in modern browsers and in legacy ones (I used IE11 for testing).

Automated Testing using Selenium

• By Github Actions it get tested using a local IE11 and a modern Edge.
• By Github Actions and BrowserStack, it get tested on other browsers. See the project BrowserStack dashboard.
• The visualization tests can be seen on the project Percy page.

If you like the demo, you can star it 🌟

kit.svelte.dev

1. Pull/Clone/degit this PR.
2. Navigate in this repo to sites\kit.svelte.dev.
3. Run pnpm install && pnpm build && pnpm preview.
4. Check the result in any legacy/modern browser you'd like.

Automated Testing (of kit package itself)

It is automatically get tested using Playwright and a custom HTTP middleware that replaces the <script> tags to simulate legacy browsers behavior (with similarity to Vite plugin-legacy internal tests). Didn't want to introduce here a new&heavy Selenium dependency thought, so I left this heavy tool for the simple demo.

In addition, I used eslint-plugin-compat (which uses caniuseit) to verify that all the JS code of the kit package is using an expected JS features, to check that the user legacy builds won't break when modifying kit package code (by accidentally adding an unexpected modern JS feature). Still it's not complete, because the Svelte team need to decide on an official browser support table (but now it's much easier with this feature).

Issue of Vite

Update: Only one open issue about web workers legacy support, that we can leave with right now in my opinion, together with the rest of the Vite community: vitejs/vite#10383 - Web workers aren't being built well for legacy. This means for example that on legacy browsers that supports web workers (e.g. IE11), the search bar on kit.svelte.dev won't work, see the discussion on the review here https://github.com/sveltejs/kit/pull/6265#discussion_r989304840 for more details.

Inner Details

This PR enable legacy support without any new configuration of SvelteKit, it is just make things to be compatible with vite legacy plugin if the user uses it in vite.config.js. The way it works is by looking at the generated Vite manifest, and check the following legacy assets that the vite legacy plugin might output:

1. legacy entry (the legacy version of start.js)
2. legacy polyfills
3. modern polyfills

Then, on server side HTML rendering, it inject the correct HTML script tags, according to what that is available, in a similar fashion to the injection of the vite legacy plugin. (Vite legacy plugin inject the scripts to the output HTML, but the output HTML is getting wiped up by SvelteKit, so this PR (hopefully) injects the correct script tags in all use cases).

This PR also solves some minor legacy compatibility issues in SvelteKit client-side routing, that cannot be fixed by polyfills.

Notice: No legacy support for dev mode. It was a decision of the creators of the vite legacy plugin.

As you can see in the demos, I suggest for end users to use the following Vite configuration with this additional polyfills, that are needed to make SvelteKit to work:

import { sveltekit } from '@sveltejs/kit/vite';
import legacy from '@vitejs/plugin-legacy';

/** @type {import('vite').UserConfig} */
const config = {
	plugins: [
		sveltekit(),
		legacy({
			// For complete list of available options, see:
			// https://www.npmjs.com/package/@vitejs/plugin-legacy#Options
			targets: ['ie >= 11'],
			additionalLegacyPolyfills: [
				'custom-event-polyfill',
				'core-js/modules/es.promise.js',
				'whatwg-fetch',
				// 'global-this' should be used so 'regenerator-runtime' wouldn't do CSP issues
				'core-js/proposals/global-this',
				'regenerator-runtime/runtime',
				'unorm',
				'path-composedpath-polyfill',
				'proxy-polyfill/proxy.min.js'
			]
		}),
	]
};

export default config;

and add also the following code at the head of script of the root +layout.svelte file:

// Loading first polyfills that are shared between for legacy&modern browsers.
import 'abortcontroller-polyfill';
import 'intersection-observer';

Important: You'll need to have this additional legacy polyfills installed as dev dependancies, as Vite plugin-legacy compiles them internally with an import directive. In this case, these additional legacy polyfills can be installed via (assuming you use pnpm): pnpm install -D custom-event-polyfill whatwg-fetch regenerator-runtime unorm path-composedpath-polyfill proxy-polyfill abortcontroller-polyfill intersection-observer

As said above, I also fixed some JS issues on legacy browsers, to make kit.svelte.dev to work (no work where done to fix legacy CSS issues). You might want to accept this PR without the changes to this site, but I don't recommend to.

Personal Experience and Opinions

It was a long journey to start understanding 3rd parties logic and bugs.

I think legacy support is crucial for many users (including me), especially by the extreme definition of legacy I gave above (not fully supporting ES modules), even if you decide to "give up on IE11". The lack of legacy support in SvelteKit made me actually use only Sapper (until now!), since I love Svelte. The reason I believe this feature is more important than other ones (such as i18n), is because the latter can be implemented by the end user or 3rd library, but legacy is (almost) impossible.

I'm very glad that the code change that is needed for legacy support is relatively minor, since the vite legacy plugin do all the hard work, although it was hard to figure out how to connect to its output correctly, and to fix 3rd party issue.

Automatic Notes (Yey! All done!)

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

• [X] It's really useful if your PR references an issue where it is discussed ahead of time. In many cases, features are absent for a reason. For large changes, please create an RFC: https://github.com/sveltejs/rfcs
• [X] This message body should clearly illustrate what problems it solves.
• [X] Ideally, include a test that fails without this PR but passes with it.

Tests

• [X] Run the tests with pnpm test and lint the project with pnpm lint and pnpm check

Changesets

• [X] If your PR makes a change that should be noted in one or more packages' changelogs, generate a changeset by running pnpm changeset and following the prompts. All changesets should be patch until SvelteKit 1.0

[changeset-bot[bot]]

🦋 Changeset detected

Latest commit: 0dfc03246da3c4a41f28d0d52ecd520dddc0f78f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@sveltejs/kit	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[Tal500]

Update: There is an issue on legacy that not happen on modern browsers: when navigating(actually, when preloading) from one page to the other, Vite doesn't load the CSS files needed for the page.

I have filled an issue on Vite: vitejs/vite#9902.

[ZaDarkSide]

I would really want this merged 😃 I need it to make my SvelteKit app to run on IE11

Despite what Microsoft declares as a defunct browser and unsupported there are surprisingly yet many instances in 2022 where IE11 is the only browser available or is a requirement that your app to function on it.

[Tal500]

I would really want this merged 😃 I need it to make my SvelteKit app to run on IE11

Despite what Microsoft declares as a defunct browser and unsupported there are surprisingly yet many instances in 2022 where IE11 is the only browser available or is a requirement that your app to function on it.

Thank you! Not only this, but also earlier version of Edge (< 18, before chromium integration) are also problematic, as well as some other legacy browsers that are newer than IE11. I just viewed IE11 as "the worst case scenario"(and the only one available in my machine), but I would like anyone else who have other legacy browser (i.e. not fully supporting ESModules browsers, e.g. old IPhones/Mac) to give it a try!

[ZaDarkSide]

I would really want this merged 😃 I need it to make my SvelteKit app to run on IE11 Despite what Microsoft declares as a defunct browser and unsupported there are surprisingly yet many instances in 2022 where IE11 is the only browser available or is a requirement that your app to function on it.

Thank you! Not only this, but also earlier version of Edge (< 18, before chromium integration) are also problematic, as well as some other legacy browsers that are newer than IE11. I just viewed IE11 as "the worst case scenario"(and the only one available in my machine), but I would like anyone else who have other legacy browser (i.e. not fully supporting ESModules browsers, e.g. old IPhones/Mac) to give it a try!

Yes, basically IE11 is the lowest denominator, there are problems with other legacy browsers also, but if it works on IE11 it will work on anything 😄

[netlify[bot]]

✅ Deploy Preview for kit-demo ready!

Name	Link
🔨 Latest commit	dd6042986adae01b3d885f9160e8511507cdfb06
🔍 Latest deploy log	https://app.netlify.com/sites/kit-demo/deploys/6314fb94113fbf00091f79f2
😎 Deploy Preview	https://deploy-preview-6265--kit-demo.netlify.app/build
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[UltraCakeBakery]

I would love to see this merged! We've been holding off building apps for older but still relatively new Tizen OS devices (mostly smart televisions, digital signage, narrowcasting displays) because they have very unreliable native browsers (random forks of chromium with limited browser API support).

[rodoch]

This would be a great PR to see merged, removing a big blocker to using Svelte Kit in contexts where legacy browser support is still necessary.

[vercel[bot]]

@Tal500 is attempting to deploy a commit to the Svelte Team on Vercel.

A member of the Team first needs to authorize it.

[Tal500]

@dummdidumm is there any reason why you put it as draft? As far for me, this is a complete PR. Yes of course I'm waiting for review, but this is not draft.

[dummdidumm]

This was just a precaution during launch day to not accidentally merge anything

[Rich-Harris]

Thank you for making this PR; I'll freely confess that I haven't paid much attention to it since it wasn't considered as part of 1.0. I didn't realise you were constantly keeping it up to date, and I want to acknowledge that there's a lot of work involved.

That said, I'm rather uncomfortable with the complexity this adds. It's a bunch of extra stuff to maintain (and a whole new test app, which will slow down every test run) for the sake of browsers that people just don't use any more. It feels to me like we'd be better off trying to make this work outside the framework core, like we do with @sveltejs/amp. Though I'd probably go so far as to say that in cases where it's truly necessary to support ancient browsers, progressive enhancement provides a more realistic approach.

[jakobbouchard]

While I agree that progressive enhancement is usually the better way to go, sometimes you need an app to work completely on older browsers. For example, I worked on a website for a federal program here in Canada. The website needed to support IE11 as well as be accessible. I decided to use Sapper with a couple polyfills, which worked very well. I needed interactivity in the website, to display 3 different components depending on inputs (see the page in question). I know the example isn't very complex, but it didn't work in Sapper without polyfills and (back then), it didn't work at all in SvelteKit.

Maybe that wasn't the best way to do it, but I also had the requirement that the website be a static one (I used the sapper export functionality). I haven't tested SvelteKit on IE11 recently (I did back then, but it was very early), but I seem to remember that it didn't degrade very gracefully. If parts of it worked it would've been okay, but I think it was completely broken, even with the polyfills I added. It worked fine for Sapper though.

Now, I was much less experienced back then (the difference ~2 years can make), and I probably did some stuff the wrong way, which probably didn't help. But I still feel like it should be possible to preserve functionality in legacy browsers. Though I do agree that it should probably be a separate module (maybe @sveltejs/legacy).

[Tal500]

Thank you for making this PR; I'll freely confess that I haven't paid much attention to it since it wasn't considered as part of 1.0. I didn't realise you were constantly keeping it up to date, and I want to acknowledge that there's a lot of work involved.

That said, I'm rather uncomfortable with the complexity this adds. It's a bunch of extra stuff to maintain (and a whole new test app, which will slow down every test run) for the sake of browsers that people just don't use any more. It feels to me like we'd be better off trying to make this work outside the framework core, like we do with @sveltejs/amp.

What I realized in my "legacy research" is that legacy support is not that hard to make, especially not within the Vite ecosystem that is very much legacy friendly. If you did into the PR implementation, the code changes that are needed for supporting legacy browsers is very minimal comparing to the gain, since the Vite legacy plugin do the whole work, and the SvelteKit job is basically just to:

1. Load the correct entry file for modern/legacy, together with the polyfill file. Thought Vite legacy plugin is doing this, it is needed since SvelteKit ignores Vite HTML output.
2. Don't interfere with legacy support, i.e. don't program in the JS code something that will be very terrible for legacy browsers support by Vite and external polyfills.
3. An optional requirement I didn't implement, is to avoid the request from the end user to load many polyfills (OK, maybe except some very classical ones, e.g. for the support of custom-event and fetch), and instead just implement them internally(i.e. ponyfills). This is however very questionable.

As I said before, the problem is not only about very old browsers like IE11, even other, much more modern(relatively) ones suffer from this issue.

For the tests maintaining issues, I did two levels of tests:

1. Basic ones that "simulates" older browsers behaviour in modern ones, they are basically a slightly improved ripoff of the Vite legacy plugin automated tests, and are part of this PR.
2. Real selenium automated test on the "SvelteKit legacy demo" repo, for both IE11 and the modern Edge browsers.

I think that maintaing the test suite in (1) is painless, and is very good (the Vite maintainers are satisfied while they having only this one). The test suite in (2) is only optional, and should be maintained in a seperate repository, for the reasons you specified. If you want to go more seriously/optimized on legacy support, there are two things you can do: (I spell them out for completeness, even though I'm impressed by you that you're not going in my direction) a. To have an external repo that run SvelteKit tests, in the same repo/fashion of https://github.com/vitejs/vite-ecosystem-ci . b. To ask for support of BrowserStack, they are good on real browsers automation, and they are happy to give their full suit for open source software (e.g. they support the caniuseit tool).

I and also many others think it's crucial that a giant thing like SvelteKit will support legacy browsers, or at least will have a limited support that will make the dream of people who wish to implement legacy support possible (i.e. "experimental support"?).

Bottom line: I don't have to have a full legacy support, I just don't want to fight SvelteKit and try to hack it, just give me (and the rest of the people who requested it) some hope.

Though I'd probably go so far as to say that in cases where it's truly necessary to support ancient browsers, progressive enhancement provides a more realistic approach.

This just make a huge disadvantage for people to use Svelte in big scales, and turns the favor for all the major alternative that do support the legacy browsers. I know Svelte metra is not about industry adoption, but the problem I said is wider.

[HelloLudger]

Neither the standard example app nor your legacy example app work on Windows PCs used by some German administration (Firefox 93, but also Chrome and Edge don't work).

As far as I can see it: The click event does not fire. There is no error in the console, which makes debugging really complicated :)

Any ideas what I could try to find the problem?

[Tal500]

Neither the standard example app nor your legacy example app work on Windows PCs used by some German administration (Firefox 93, but also Chrome and Edge don't work).

As far as I can see it: The click event does not fire. There is no error in the console, which makes debugging really complicated :)

Any ideas what I could try to find the problem?

It must be bacuase of some weird reason... The simple demo is manually tested by me with:

• IE11
• chrome 15
• latest firefox

And additionally, it is being tested automatically by Selenium on IE11 and the latest Edge, see the latest Github action excecution .

In addition, Firefox 93 is way so modern, so the regular Svelte demo should work out of the box.

The only thing I can think about is some network restriction, e.g. from loading JS files, or even worse - manipulating their content in a middleware. Can you check the network console of the browser to see that the scripts with the "nomodule" attribute in the generated HTML, are being loaded on the legacy browsers?

Can you also give a more careful reproduction? Can you test all the following:

• Regular SvelteKit demo by local build and preview
• My simple legacy demo by local build and preview
• The cloudflare online link to my online hosted legacy demo.

You probably understand this - but on the first two, don't run pnpm dev, but rather run pnpm build && pnpm preview.

[HelloLudger]

Thank you, I will see what I can do. Since I have no direct access to the PCs that have the problem, I am very limited So don't wait for my feedback.

:-(

[perqa]

@Rich-Harris It not only "for the sake of browsers that people just don't use any more". There's a big segment of embedded browsers, for example in Connected TVs, where browser updates are rare or non-existent. Svelte would be a good fit for that segment considering performance, since those devices often are inherently slow, but many of them require legacy support.

[Tal500]

@Rich-Harris It not only "for the sake of browsers that people just don't use any more". There's a big segment of embedded browsers, for example in Connected TVs, where browser updates are rare or non-existent. Svelte would be a good fit for that segment considering performance, since those devices often are inherently slow, but many of them require legacy support.

Not only this - but SvelteKit isn't nice to "not so legacy browsers" as IE11 as well!

I think it's give also some confident to know which browsers should work with SvelteKit, no matter if you like legacy or not. I believe that asking for BrowserStack support is a valid option, as I mentioned (that they like to support open source repos manual/auto test).

[Tal500]

Update: I used eslint-plugin-compat (which uses caniuseit) to verify that all the JS code of the kit package is using an expected JS features, to check that the user legacy builds won't break when modifying SvelteKit code. Still it's not complete, because the Svelte team need to decide on an official browser support table (but now it's much easier with this feature). This may solve some concern that @Rich-Harris mentioned before.

[HelloLudger]

@Tal500

some network restriction, e.g. from loading JS files

This is the problem. They think that Svelte is including some web-tracking-scripts, so they block them. 0 javascript is delivered to the browser.

[chipndahla]

@Rich-Harris It not only "for the sake of browsers that people just don't use any more". There's a big segment of embedded browsers, for example in Connected TVs, where browser updates are rare or non-existent. Svelte would be a good fit for that segment considering performance, since those devices often are inherently slow, but many of them require legacy support.

I can 100% echo this. Sveltekit is a perfect fit for Smart TVs thanks to code performance. But legacy browser support is a key feature since the their Web Engines are very old and never updated. Was surprised Sveltekit don't support it.

[7antra]

Hello,

I would like to add an opinion here that I hope could accelerate a decision regarding this PR.

At RadioFrance (radiofrance.fr) we have been using Svelte and Sveltekit (and before that, Sapper) for over two years now. And we are sincerely happy to promote this framework on a site with 8 million visits every month, 7 different radios that broadcast live and podcasts continuously, and thousands of new press articles each month.

This week, and after a lot of hard work, we moved to v1.x.x (thanks @Rich-Harris for the migration post which helped us a lot, and congratulations again for all the work done by all the maintainers); however we noticed today that our site is no longer available for many users with old devices.

Maybe by habit it is easy to consider that legacy is always < 1% but for us, less than 1% is still tens of thousands of people who write to us to report that they haven’t been able to listen to their favorite show since Monday. Plus, being a public service, it is quite important to us that our site remains as accessible as possible, even if it means supporting ancient browsers.

The progressive enhancement option would be possible, but would require months of refactoring, as the webapp was not built with this in mind from the start.

We think that we are left with (and it’s a shame, today) having to take such a drastic decision as a rollback (even if we hope it’s only temporary) since @vite/legacy-plugin doesn’t work with SvelteKit.

Maybe there is another solution that we missed, if so we would love to hear from you 🙏

[Tal500]

@Rich-Harris It not only "for the sake of browsers that people just don't use any more". There's a big segment of embedded browsers, for example in Connected TVs, where browser updates are rare or non-existent. Svelte would be a good fit for that segment considering performance, since those devices often are inherently slow, but many of them require legacy support.

I can 100% echo this. Sveltekit is a perfect fit for Smart TVs thanks to code performance. But legacy browser support is a key feature since the their Web Engines are very old and never updated. Was surprised Sveltekit don't support it.

Hello! First, in my own personal project I'm using this fork of this PR, which gives a full legacy compatibility, see the details in the head description.

Secondly, I would wish that "less than 1%" will be accurate! Here are the details:

1. The total amount of browsers usages that doesn't support fully ESModules is way more than 1%, acoording to "caniuseit" at least.
2. SvelteKit uses many advanced standard features that are not supported only in "mid-legacy" browsers, say Firefox < 84 if I remember correctly. The current moto of the development as far as I can tell, following the automated Playwrite E2E testing, is supporting only the latest browsers available.

[bleucitron]

@Rich-Harris It's a bunch of extra stuff to maintain [...] for the sake of browsers that people just don't use any more

@7antra but for us, less than 1% is still tens of thousands of people

I'm not fully aware of all the technical constraints that justify this is not merged yet, but "tens of thousands of people" is a great deal of users.

I love that the Svelte way is to help enforce web accessibility as much as possible (especially when you're terrible at it, like me), and I believe that old browsers compatibility is accessibility ("old" to some extent of course, which could be debated).

I strongly believe that the compatibility of @vitejs/plugin-legacy should be included, in one way or another. Whether it's inside or outside the framework core, I do not have the knowledge or skills to have a strong opinion about it.

[bfanger]

I've created tvkit a proxy server that transforms a vite dev server into something that can be processed by older browsers.

Start your dev server normally and then run:

npx tvkit@latest serve --browser "ie 11"

Now you're able to access your SvelteKit dev server in an older browsers on http://localhost:3000/

If your building using the adapter-static, tvkit also has an experimental build command to process the generated static build:

npx tvkit@latest build ./build --out ./dist --browser "ie 11"

[chipndahla]

I've created tvkit a proxy server that transforms a vite dev server into something that can be processed by older browsers.

Start your dev server normally and then run:

npx tvkit@latest serve

Now you're able to access your SvelteKit website in an older browsers on http://localhost:3000/

If your building using the adapter-static, tvkit also has a build command to process the generated static build:

npx tvkit@latest build ./build --out ./dist

Fantastic! Sweet news for us! Just gave you your first star :-) Will test and get back with results!

[pasqui23]

On 07/02/23 18:13, Andreas Dahlström @.***> wrote:

I've created tvkit <https://github.com/bfanger/tvkit> a proxy server
that transforms a vite dev server into something that can be
processed by older browsers.

Start your dev server normally and then run:

npx ***@***.*** serve

Now you're able to access your SvelteKit website in an older
browsers on http://localhost:3000/ <http://localhost:3000/>

If your building using the adapter-static
<https://github.com/sveltejs/kit/tree/master/packages/adapter-static>, tvkit also has a build command to process the generated static build:

npx ***@***.*** build ./build --out ./dist

If I have a site on Vercel, how do I use TVKit?

[bfanger]

Try too keep this GitHub thread about the @vitejs/legacy PR.

For questions and issues about TVKit use the https://github.com/bfanger/tvkit/issues page.

[UnrilWever]

Why hasn't it been merged yet?