diff --git a/.vitepress/theme/styles/content.scss b/.vitepress/theme/styles/content.scss index be466a45..9904deae 100644 --- a/.vitepress/theme/styles/content.scss +++ b/.vitepress/theme/styles/content.scss @@ -91,3 +91,8 @@ .content-container .VPDocFooter { margin-top: 30px; } + +.mx-auto { + margin-left: auto !important; + margin-right: auto !important; +} diff --git a/.vitepress/theme/styles/fixes.scss b/.vitepress/theme/styles/fixes.scss index 4835e896..4b8f2e2e 100644 --- a/.vitepress/theme/styles/fixes.scss +++ b/.vitepress/theme/styles/fixes.scss @@ -220,6 +220,10 @@ margin-top: 40px !important; } +.vp-doc h2 .header-anchor { + top: 16px; +} + .vp-doc p > strong > a, .vp-doc p > a, .vp-doc li > strong > a, diff --git a/docs/platform/webcontainers/assets/chrome-memory-saver.png b/docs/platform/webcontainers/assets/chrome-memory-saver.png index 30885622..abceddf6 100644 Binary files a/docs/platform/webcontainers/assets/chrome-memory-saver.png and b/docs/platform/webcontainers/assets/chrome-memory-saver.png differ diff --git a/docs/platform/webcontainers/assets/chrome-settings-popups.png b/docs/platform/webcontainers/assets/chrome-settings-popups.png new file mode 100644 index 00000000..b8de4ec3 Binary files /dev/null and b/docs/platform/webcontainers/assets/chrome-settings-popups.png differ diff --git a/docs/platform/webcontainers/assets/firefox-settings-popups.png b/docs/platform/webcontainers/assets/firefox-settings-popups.png new file mode 100644 index 00000000..55d1d23c Binary files /dev/null and b/docs/platform/webcontainers/assets/firefox-settings-popups.png differ diff --git a/docs/platform/webcontainers/browser-config.md b/docs/platform/webcontainers/browser-config.md index 8cab05a1..5e4e5b4b 100644 --- a/docs/platform/webcontainers/browser-config.md +++ b/docs/platform/webcontainers/browser-config.md @@ -22,15 +22,30 @@ With Chrome's defaults, starting with version 118 or later, you should get a pre Read on if you run into issues or want an even smoother experience. -Previews opened in a separate tab will require you to connect them to the editor. You usually get prompted to click on a button to do that. However, you might do that more frequently than expected with Chrome's [memory saver][CHROME_MEMORY_SAVER]. To avoid it, you can add the following exception in [chrome://settings/performance](chrome://settings/performance): +### Previews in a separate tab {#chrome-preview-separate-tab} + +Previews opened in a separate tab are not connected by default to the editor and require an extra step. To complete this step, you are usually prompted to click a button. + +This can happen automatically if your popups settings, [chrome://settings/content/popups](chrome://settings/content/popups), are adjusted with the following exception: + +``` +https://[*.]webcontainer.io +``` + +Chrome popups settings showing the *.webcontainer.io origins as exceptions + +Once done, whenever the preview needs to reconnect to the editor, it will open a popup that gets immediately closed. + +Lastly, if Chrome's [memory saver][CHROME_MEMORY_SAVER] is turned on, this step might be necessary more often than required. To avoid it, you can add the following exception in [chrome://settings/performance](chrome://settings/performance): ``` +https://webcontainer.io https://stackblitz.com ``` -Once done, you should see something similar to this: +Your performance settings should be similar to this: -Chrome performance settings showing the memory saver section with an exception for stackblitz.com +Chrome performance settings showing the memory saver section with an exception for stackblitz.com ### Enabling Service Workers {#chrome-service-workers} @@ -45,7 +60,7 @@ The first option should be preferred because this is a [new feature][GOOGLE_SP] Visit `chrome://flags/#third-party-storage-partitioning` and choose `Enabled` in the drop down. In recent version of Chrome, choosing the `Default` value should work too. -Chrome flags showing the third-party Storage Partitioning option enabled. +Chrome flags showing the third-party Storage Partitioning option enabled. #### Or add exceptions for Stackblitz @@ -59,11 +74,11 @@ https://[*.]webcontainer.io For instance, in Chrome, go to `chrome://settings/cookies` and add those exceptions in the “Sites that can always use cookies” section. -Chrome cookie settings with an empty list of “Sites that can always use cookies”. +Chrome cookie settings with an empty list of “Sites that can always use cookies”. -Chrome cookie settings showing a modal dialog for adding a site to list of third-party cookie exceptions. +Chrome cookie settings showing a modal dialog for adding a site to list of third-party cookie exceptions. -Chrome cookie settings with exceptions for stackblitz.io and local.webcontainer.io domains. +Chrome cookie settings with exceptions for stackblitz.io and local.webcontainer.io domains. :::details Advanced: enabling Service Workers for a single project @@ -83,7 +98,9 @@ Note that the list of blocked domains might look different for you. In particula ::: -## Firefox: enabling Service Workers {#firefox-service-workers} +## Firefox + +### Enabling Service Workers {#firefox-service-workers} When Firefox’s Enhanced Tracking Protection is configured in “Custom” mode with the cookie blocking option set to “All cross-site cookies”, Firefox will block the Service Workers used by WebContainers. @@ -97,7 +114,8 @@ To do so, visit `about:preferences#privacy` to check what your current settings The Firefox “Privacy & Security” settings page showing that Enhanced Tracking Protection is set to “Custom”, and to “Cookies: All cross-site cookies (may cause websites to break)”. To add exceptions for StackBlitz, scroll down to the “Cookies and Site Data” section, click on “Manage Exceptions…”, and add exceptions for the following sites: @@ -110,11 +128,25 @@ https://webcontainer.io The Cookies and site data exceptions management window in Firefox settings. It shows a couple entries for stackblitz.io and webcontainer.io, both with the value “Allow”. Don’t forget to click “Save Changes”. Then you should be able to reload the tab with your StackBlitz project, and hopefully everything should work! +### Previews in a separate tab {#firefox-preview-separate-tab} + +Previews opened in a separate tab are not connected by default to the editor and require an extra step. To complete this step, you are usually prompted to click a button. + +This can happen automatically if your popups settings, [about:preferences#privacy](about:preferences#privacy), are adjusted with the following exception: + +``` +https://webcontainer.io +``` + +Firefox popups settings showing the webcontainer.io site allowed as an exception + + ## Brave: enabling Service Workers {#brave-service-workers} By default, Brave’s “Shields” feature blocks [Service Workers][MDN_SERVICE_WORKER] and cookies from third-party domains. @@ -123,19 +155,19 @@ To allow WebContainers to run in Brave, you will need to add an exception for St 1. Visit a WebContainers-based project, for instance https://stackblitz.com/edit/nextjs. The project’s boot sequence might stay stuck on the “Running start command” step: -![Screenshot of Brave on a WebContainers project with the Brave Shields feature on. Loading the project’s web server is stuck on the last step.](./assets/brave-stuck-project.png) +Screenshot of Brave on a WebContainers project with the Brave Shields feature on. Loading the project’s web server is stuck on the last step 2. Click on the “Shields” icon at the right of the address bar, then click on “Advanced View”. -Screenshot showing the Shields configuration popup for stackblitz.com. +Screenshot showing the Shields configuration popup for stackblitz.com. 3. In the advanced view, change the “Cross-site cookies blocked” option to “All cookies allowed”. -![Screenshot showing the advanced view of the Shields configuration popup, with a drop-down selector for cross-site cookie permissions.](./assets/brave-shields-details.png) +Screenshot showing the advanced view of the Shields configuration popup, with a drop-down selector for cross-site cookie permissions. Brave will reload the page, and you should get a working project: -![Screenshot of Brave on a WebContainers project with the Brave Shields feature tweaked to allow third-party cookies and Service Workers. Loading the web server works, and shows the default page for Next.js’s starter project.](./assets/brave-working-project.png) +Screenshot of Brave on a WebContainers project with the Brave Shields feature tweaked to allow third-party cookies and Service Workers. Loading the web server works, and shows the default page for Next.js’s starter project. ## Edge: enabling WebAssembly {#edge-webassembly}