Website issues you could encounter

Polypane is really good at surfacing issues with websites. For example with our debug tools, outline panel and accessibility panel.

A key thing to realize is that there are certain issues that only happen in, or are more severe because of, multiple panes. Websites are frequently coded in such a way that one session requests one page one time, but with Polypane, one sessions requests a page multiple times, potentially with different device capabilities.

This can catch people off guard, thinking Polypane is not working correctly when it is actually surfacing incorrect assumptions or issues in their website.

To get a better understanding of the implications this has, please read our docs on the mental model of Polypane's browser contexts. Many of the issues listed below are a direct result of this.

Login/Logging in on websites not succeeding

Some sites prevent users from logging in from multiple panes at once for various reasons:

• They dont allow multiple login attempts,
• They have a login cooldown timer,
• They automatically log you out when using different user agents
• ...or other mitigation strategies

All of these will make it look like Polypane can't log into a website. 9 out of 10 times this is remedied by logging in using a single pane, like in focus or full layout, and then going back to multiple panes.

If that doesn't work, you can log in using the Browse panel and refresh the panes. Since the session is shared across all panes and the browse panel, this should log you in everywhere.

log in to websites using SSO, oAuth or login redirection

To log in to sites using federated login, similarly switch to the focus or full layouts or log in using the browse panel. Polypane syncs the session across all panes, so after a reload you'll be logged in everywhere.

The reason for needing this is due to how federated logins like SSO or oAuth work:

• Many SSO or oAuth solutions depend on multiple redirects and POST requests. If Polypane syncs these redirects during the process, this can interrupt the redirection flow and cancel it.
• Many SSO or oAuth solutions see multiple simultaneous logins, or logins with different user agents, as a risk and will abort the sign-in process.

While Polypane prevents form submissions from happening in multiple panes, federated logins are often instantiated by javascript, which we can not catch. When this happens in multiple panes, multiple different popups might get opened, or the site will generate and invalidate multiple CSRF tokens (one by one for each request) which can all cause logins to fail.

There is no way to work around this while showing the page multiple times and syncing interactions. Luckily, the solutions mentioned above are robust and easy.

Non-persistent authentication

If your site logs you out on every refresh, Polypane can unexpectedly log you out when it needs to sync up the navigation state between panes.

Sessions, user interactions and navigation are all synced between panes. This means that when you're logged in anywhere, you're logged in everywhere. It makes sure that panes all get the time needed to navigate on their own as a result of a synced user interaction so syncing happens naturally.

However as a last resort, it updates the URL of panes that have not navigated yet. If this subsequently triggers a log out event, that will then get synced to all other panes as well.

The only way to work around that is to prevent logging out when Polypane is detected or finding where the click events are not correctly synced (a common issue is using different UI elements on different screen sizes and making sure you use the same UI elements across sizes.

Performance issues

Polypane runs the same code in each pane so performance bottlenecks are quicker to show.

Roughly put, Polypane needs the same amount of resources for each pane as Chrome needs for a single tab. It's essentially rendering multiple full Chrome tabs at the same time, with the CPU and memory requirements that brings, and without the ability to throttle all the non-active tabs (because all panes need to be kept in sync).

This means that while your site might perform well on your fast computer in a single tab, when that same code is executed 3, 4 or 5 times, bottlenecks start to appear.

Those bottlenecks were always there, Polypane just enlarges them. They will also be there when a user has other resource intensive tabs open (like playing a video on YouTube) or has your page open on a less powerful device than yours.

If you notice performance issues, try to run Polypane with this web page, and see if the performance issues persist.

If they get resolved, please tell us the URL so we can figure out what that bottleneck is and either help you improve your website or help us improve our application. We really appreciate this.

There are ways to improve performance in Polypane, check out the Performance docs for tips on optimizations you can do.

Rate limited APIs

Each pane in Polypane requests its own resources, so you download them for each pane separately. A rate limited API reaches that limit faster the more panes you have. This is essential for emulation, where your server might send different resources depending on the user agent and other properties. But if your server limits the number of calls you can make, or you have a rate-limited API you use, Polypane will reach that limit faster the more panes you use.

If you depend on an API with rate limiting for your development work we highly recommend you replace it with a mock server, caching proxy or disable it.

Each pane in Polypane contributes to your page load statistics

Because Polypane downloads and executes your page for each pane, any anayltics tool will record each visit as well which could lead to quite a spike in your stats after using Polypane.

In general it's best practice to configure your analytics tools to ignore your own IP address or otherwise tell it to ignore visits from Polypane. You could also configure your site/app such that the analytics scripts is only ever loaded in production and not in development.

Simple Analytics automatically filters Polypane visits

If you use Simple Analytics for your visitor stats, any visit with Polypane is automatically filtered out of the results without you having to do anything.

Not syncing between panes

The most common reason for input not syncing between panes is that you're not using the same elements across sizes, or that the same element isn't available in all panes (for example, with HTML that is conditionally added through JS)

You can prevent this by using the basics of good web development and making sure that the DOM is built up logically and is accessible. Polypane syncs events on the same elements across panes. If those elements aren't available, no syncing is possible. There's usually two common reasons for this:

• Duplicated UI for different screen sizes: for example, a mobile menu and normal menu that are different elements.
• Conditional rendering: elements that are only added or removed to the DOM after a certain event, like a click or a scroll.

When you click the normal menu in one pane, that doesn't exist in the other pane, so there is no element for the click to sync to in the other pane. Rather than building and maintaining two sets of components, it's better to build one set of components and use media queries to style them appropriately for the viewport size. This has additional benefits for maintainance, performance and accessibility.

When you have DOM that you add and remove on click or hover, Polypane again would try to sync to an element that doesn't exist in the other pane. Rather than manipulating the DOM directly, you can use CSS classes to show and hide elements. This has many additional benefits for discoverability, SEO, error recovery and more.

Mobile rendering

Pages might look fine in Polypane but are zoomed out on actual mobile phones. This is because Polypane by default will use "desktop" rendering. You can use the emulation options to toggle to mobile rendering.

Desktop rendering is faster and will make your site look responsive even if you don't set the right viewport meta tag.

Mobile phones however, have to support the entire internet, including sites that were never optimized for mobile devices in the first place. So when a viewport tag with the right value is not available, It will pretend it's much wider and then zoom out the site to fit.

When you're missing a viewport tag, mobile devices will think you didn't make a responsive website, and render it differently.

Tldr: Stick to our responsive design ground rules to not be surprised when testing on actual devices.

Domains not forwarding correctly

Forwarding from HTTP to HTTPS (upgrading) or from the bare domain to www. is something that has to be configured correctly on the server. Incorrect configuration can lead to behavior where, if your SSL certificate does not cover all (sub)domains, one of the urls will actually cause an SSL certificate error, or attempt to redirect to an unconfigured domain.

Unfortunately, having an incorrectly configured server happens so often that modern browsers like Chrome and Firefox detect these issues and will fix them for you, without confronting the end user with the issues causes by an incorrectly configured server.

Polypane is a browser for developers, so it does not compensate for incorrectly configured servers. It will either not forward, or show an SSL error, in situations where Chrome won't.

If you need to explain this to back-end developers or devops, and they point to Chrome working, you can ask them to use Polypane or test all variations of the URL with curl, and they'll see which one fails soon enough.

Non standard navigation

If you use non standard navigation, Polypane has no way of knowing it should sync anything between panes.

Polypane can accurately sync regular HTTP navigation as well as the History API.

This means that any routing solution that uses the History API (React router, Gatsby, Next, Vue router, Reach router, Angular router, etc) works really well in Polypane. In fact this website is built using Gatsby and its built-in routing.

When you don't use the browser-supported navigation methods however, Polypane can only depend on input syncing to maintain the state between panes. Equally as important, assistive technologies will also have a tough time keeping your visitor informed of where they are.

We highly recommend you use a modern and battle tested routing solution, as it will massively improve the user experience.

Third party scroll syncing issues with Browsersync or Ghostery

Tools like Browsersync or Ghostery leads to a janky experience in Polypane because Polypane syncs faster than those tools.

Polypane already syncs scrolling, navigation and input events. Polypane does this in-process, but tools like Browser-sync and Ghostery use a local webserver. This makes them (slightly) slower than Polypane. Because of that these tools can actually reset your scrolling: they're syncing state from a moment ago while Polypane has already synced the next scroll event, so they cause your site to "scroll back". It's a situation where milliseconds matter and the extra round-trip to a server is enough to get the wires crossed.

When Polypane detects that you're using Browser-sync's scroll sync feature the built-in scroll syncing is disabled. We recomment that when you use these tools, you turn their syncing features off. For Browser-sync, it's called "ghost mode".