shopper
eCommerce
TypeScript
š shopper
š live demo of shopper
š¹ļø also see the codepen demo
š° plug your shopify store onto any website!
šļø full shopping cart experience with shopify checkout button
āØ easy html installation! works on any website
š± users get currency conversions to view prices
š free and open source, just for you
āØ easy html install
-
add
<script>elements in your html<head><script type="importmap-shim"> {"imports": { "shopper/": "https://unpkg.com/shopper@0.2/", "shopper": "https://unpkg.com/shopper@0.2/x/shopper.js" }} </script> <script type="importmap-shim" src="https://unpkg.com/shopper@0.2/x/importmap-cloud.json"></script><script defer type=module-shim> import “shopper/x/install-xiome-menu-system.js” import “shopper/x/install-shopper.js” </script>
<script defer src=“ https://unpkg.com/es-module-shims@1.5/dist/es-module-shims.wasm.js"></script>
<p> note: this technique uses es-module-shims, and if you’re already using es-module-shims for something else on the page, just don’t repeat that last line (you only want that once per page). </li> <li> <strong>place a <code><shopper-config></code> element in your html <code><head></code></strong></p> <pre><shopper-configmock base-currency=“cad” currencies=“usd gbp eur” ></shopper-config>
<p> the above config is in <code>mock</code> mode, which lets you play around with fake products<br /> we’ll explain how to connect your real store in the next section </li> <li> <strong>place the <code><shopper-cart></code> element somewhere on your page</strong><br /> this is all you need</p> <pre><shopper-cart></shopper-cart></pre> <p> however, you may wish instead to place the cart inside a menu system (like in the demo) </p> <pre><xio-menu sticky><xio-menu-item>
<shopper-button></shopper-button> <shopper-cart slot="panel"></shopper-cart></xio-menu-item> </xio-menu>
<p> also, the cart can take a <code>checkout-in-same-window</code> attribute, if you want to avoid a popup during checkout </p> <pre><shopper-cart checkout-in-same-window></shopper-cart></pre> </li> <li> <strong>list products for sale</strong><br /> list all store products with a <code><shopper-collection></code> element and the <code>all</code> attribute<br /> <strong>note:</strong> your products have to be in any collection, for them to appear this way.</p> <pre><shopper-collection all></shopper-collection></pre> <p> list a single collection. get the <code>link</code> by copying and pasting the url from your shopify admin panel </p> <pre><shopper-collection link="https://dev-bakery.myshopify.com/admin/collections/424441479"></shopper-collection></pre> <p> display a single product for sale. </p> <pre><shopper-product link="https://dev-bakery.myshopify.com/admin/products/10232162183"></shopper-product></pre> <p> again, you simply copy the link from the product page’s url in the shopify dashboard.<br /> you actually don’t need the whole link, just the numbers from the end part of the url. </li> <li> <strong>customize the display of products</strong></p> <pre><shopper-productlink=“10232162183” href="/products/avocado-toast” show-image image-size=“300x200” ></shopper-product>
<ul dir="auto"> <li> <code>link</code> ā product url from the shopify admin dashboard </li> <li> <code>href</code> ā make the item clickable, taking the user to any url </li> <li> <code>show-image</code> ā attach this attribute if you want the product’s first image to be displayed </li> <li> <code>image-size</code> ā specify the dimensions the image should be loaded at</p> <ul dir="auto"> <li> if omitted, the image will be full-resolution </li> <li> <code>image-size="200"</code> will constrain the image to <code>200x200</code> </li> <li> <code>image-size="300x200"</code> will constrain the image to <code>300x200</code> </li> </ul> </li> </ul> <pre><shopper-collectionshow-images image-sizes=“300x200” ></shopper-collection>
<h2 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content--connect-shopper-to-your-real-shopify-store" class="anchor" aria-hidden="true" href="#-connect-shopper-to-your-real-shopify-store"></a>š” connect shopper to your real shopify store
</h2>
<ul dir="auto">
<li>
<strong>replace your <code><shopper-config></code></strong><br /> use the example below, but use your own values!</p> <pre><shopper-config
base-currency=“cad” currencies=“usd gbp eur” shopify-domain=“dev-bakery.myshopify.com” shopify-storefront-access-token=“5f636be6b04aeb2a7b96fe9306386f25” ></shopper-config>
<li>
<strong>get your <code>baseCurrency</code> correct!</strong><br /> this is the same as your store base currency setting in shopify.
</li>
<li>
<strong>if you provide <code>currencies</code>, they’ll be available for the user to choose</strong><br /> this is how you specify which currencies you want to allow the currency conversion system to use.<br /> see crnc for more details.
</li>
<li>
<strong>obtain your <code>shopify-domain</code> and <code>shopify-storefront-access-token</code></strong></p> <ul dir="auto">
<li>
login to your shopify store’s admin area
</li>
<li>
copy your <code>shopify-domain</code> from your browser address bar’s url
</li>
<li>
create a new private app (a connection point for your website) <ol dir="auto">
<li>
click on the “apps” section on the left sidebar
</li>
<li>
click the sneaky “Manage private apps” link
</li>
<li>
check on the agreements and stuff to enable private apps
</li>
<li>
click “Create new private app”
</li>
<li>
enter the app name, and developer email
</li>
<li>
skip the whole “Admin API” section
</li>
<li>
enable “Storefront API” and check on all “Read” permissions
</li>
<li>
save your app
</li>
</ol>
</li>
<li>
copy your app’s “Storefront access token” (NOT TO BE CONFUSED with the “API Token”) and use this as your <code>shopify-storefront-access-token</code>
</li>
</ul>
</li>
</ul>
<h2 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content--customize-shoppers-appearance-with-css" class="anchor" aria-hidden="true" href="#-customize-shoppers-appearance-with-css"></a>š
customize shopper’s appearance with css
</h2>
<ul dir="auto">
<li>
<strong>shopper looks very plain and ugly by default</strong><br /> that’s because it’s designed to be customized.<br /> shopper only comes with bare-bones layout styles, so it’s as easy as possible to customize to match your store
</li>
<li>
<strong>shopper’s web components render to light-dom</strong><br /> this allows complete css customization
</li>
<li>
<strong>basic css knowledge is required for visual customizations</strong><br /> the recommended workflow, is to right-click inspect-element anything you want to customize, look at it’s element names and class names, and then write some CSS rules on your page.<br /> you have to be a bit of a nerd to get this done.<br /> we’re open to somebody writing some standard themes so people can avoid this step in the future
</li>
</ul>
<h2 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content--under-the-hood" class="anchor" aria-hidden="true" href="#-under-the-hood"></a>š©āš§ under the hood
</h2>
<ul dir="auto">
<li>
published as an npm package <code>shopper</code>
</li>
<li>
written in typescript
</li>
<li>
es modules
</li>
<li>
universally-compatible web components
</li>
<li>
only makes network requests to shopify, and to <a rel="nofollow noopener" target="_blank" href="https://www.bankofcanada.ca/valet/docs">https://www.bankofcanada.ca/valet/docs</a> to fetch exchange rates via crnc
</li>
<li>
saves cart data to <code>localStorage</code> to keep track of your cart between page loads
</li>
</ul>
<h2 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content--made-with-open-source-love-just-for-you" class="anchor" aria-hidden="true" href="#-made-with-open-source-love-just-for-you"></a>š made with open source love, just for you
</h2>
<ul dir="auto">
<li>
please file issues and collaborate š»
</li>
<li>
we should make some example css themes that look good so people don’t have to customize the css
</li>
<li>
we should publish an optimized rollup build for end-use (not suitable for consumption from apps with their own build)
</li>
</ul>