polaris-turbo-bridge

v0.3.1

Published

5 months ago

Make Shopify Polaris Web Components (<s-button>, <s-link>) navigate with Hotwire Turbo in Rails or any HTML-over-the-wire app.

0High
0Medium
0Low

pasilobus

polaris turbo hotwire rails importmap shadow-dom web-components

Polaris‑Turbo‑Bridge

Let every <s-button> and <s-link> from @shopify/polaris behave like a first‑class Hotwire Turbo Drive link.

Zero dependencies, <2 kB minified, works with Import‑Map, esbuild, Vite, Webpacker.

Why?

Polaris Web Components render their own <a> tag inside Shadow DOM.
Turbo Drive’s global click listener never “sees” that anchor, so navigation is blocked.
This bridge captures clicks on the host element, honours data‑turbo-* attributes, and delegates to Turbo.visit() (or a hidden form for REST verbs).

<s-button href="/posts" icon="products">Posts</s-button>

<s-button href="/posts/42"
          data-turbo-method="delete"
          data-turbo-confirm="Really?"
          tone="critical">
  Delete
</s-button>

Install

1 · Load the Polaris Web Component bundle

Polaris Web Components are distributed only as a pre‑built script. Add it once in your HTML (Rails layout or equivalent):

<!-- app/views/layouts/application.html.erb -->
<head>
  …
  <script src="https://cdn.shopify.com/shopifycloud/app-bridge-ui-experimental.js"></script>
</head>

2 · Pin and start the Turbo bridge

Rails 8 + Import‑Map

pin "polaris-turbo-bridge",
    to: "https://ga.jspm.io/npm:[email protected]/index.js",
    preload: true

// app/javascript/application.js
import "@hotwired/turbo-rails";
import { PolarisTurboBridge } from "polaris-turbo-bridge";

PolarisTurboBridge();

npm / pnpm / yarn

npm i polaris-turbo-bridge

import { PolarisTurboBridge } from "polaris-turbo-bridge";
PolarisTurboBridge();

Features

GET navigation via Turbo.visit()
data-turbo-method (delete, patch, etc.) via hidden form with CSRF token
data-turbo-confirm native prompt (override for custom modals)
data-turbo-frame partial updates
Respects ⌘‑click, Ctrl‑click, Shift‑click, target="_blank"
Works everywhere Turbo works (Rails, Phoenix, Django, Laravel…)

API