renew - hotswap CSS & live reloads with Shopify Themekit

TL;DR: A page reloader that hot swaps css, and reloads browser windows for other files while you are developing awesome themes on Shopify.

1. Install
2. Add the notification to themekit watch
3. Add the script to your theme for the client
4. Start the server

Beta:

This project is in Beta and being adjusted while its in use so there may be some breaking changes, but we dont foresee many.

Getting started

Renew ties up to a notification event emmited by Themekit, so Themekit is as requirement.

There are a numnber of ways to include "renew" in your theme project below are a few:

1. Low config cdn / npx setup ( great for testing it out but slower)
2. Low config local installation ( great for basic themekit setups & fast)
3. Included in your dev bundle (in dev but useable)
4. Installer ( in dev ) - adds a js file, snippet & options section to enable and disable

Note:

Renew uses a locally runnign server to act as the go between from a shopify notification that a file has been updated and any number of browsers / tabs. We additionally have a client script that needs to load on the theme to make this communication possible. These two connected with a ThemeKit notification that sends a POST request to the server. Keep these in mind.

1. Low config cdn based installation

Great for giving it a quick whirl with minimal installation.

- 1.1. Add the client to your theme layout

Add the script to your layout (normally /layouts/theme.liquid) just before the </body> tag.

<script src="https://unpkg.com/@weareeight/renew/dist/client.js" defer="defer"></script>

- 1.2. Add a notification flag to Themekit

Locally Installed

theme watch --notify=http://localhost:5000

Node CLI wrapper

shopify-themekit watch --notify=http://localhost:5000

- 1.3. Start the server

You can start a server as an executable without installing it in your project anything, great to test it out.

Run the command npx @weareeight/renew --server

This will load the server, leave the terminal open and start your usual themekit watch.

- 1.4. Startup your Themekit

Leave the server running in its terminal, and start up your themekit watch in a seperate terminal. BUILD AWESOME THINGS!

2. Local installation

- 2.1 Install the package

NPM

npm install @weareeight/renew --save-dev

Yarn yarn add @weareeight/renew --dev

This will allow the cli to be used locally to start the server

- 2.2 Setup a node script to launch the server

Add a script to your package.json scripts list

{
  "scripts" : {
    "renew:server":"renew-cli --server"
  }
}

There is further config available, see advanced usage.

- 2.3 Add the notification flag to your Themekit task

Locally Installed

theme watch --notify=http://localhost:5000

Node CLI wrapper

shopify-themekit watch --notify=http://localhost:5000

Node function

add notify: 'http://localhost:5000' to your flags object where you instantiate your watch.

- 2.4 Add the client to your theme layout

Add the script to your layout (normally /layouts/theme.liquid) just before the </body> tag.

<script src="https://unpkg.com/@weareeight/renew/dist/client.js" defer="defer"></script>

We do have this as a file and function if you would prefer to load this to assets, ./node_modules/@weareeight/renew/dist/client.js the CLI will have some tools shortly to do this for you.

- 2.5 Start up the server and your watch

You will need to start the renew:server and your themekit watch along side each other, you can do these in seperate terminals or make use of a great tool like npm-run-all to run these in parallel in a single terminal.

Start Themekit your themelit watch command - make sure it includes the notify above

start the renew server

npm run renew:server

- 2.6 Build awesome things!

Open up your theme on the front end or the customizer and build awesome things, while the page hot swaps or reloads depending on the changes you are making. Check the console on the site or the terminal for feedback of what renew is up to.

Include the client it in your build / dev tooling

- As a module import

The renew client can be included as a module, using one of two methods.

Default, starts the socket client with default values

import {start} from '@weareeight/renew'

// start it up based on your criteria
start() 

Configurable

import {renew} from '@weareeight/renew'

// start it up based on your criteria
// reference the Advanced config for the params
renew(5050, 'ws://localhost', 4000) 

Both of these options will start the client, one with defaults and one ytou can configre to align with a custom server config.

- Included in your webpack

We assume that you have some understanding of how to configure webpack. We are not going to unpack this in depth, but a common approach would be to include the zero config client or a custom inclusion as an entry into your bundle if it is in dev mode.

const entries = isDev ? ['./src/theme.js', './node_modules/@weareeight/renew/dist/client.js'] : ['./src/thheme.js']; Where is dev looks at the current environment to detirmine if the bundle includes the client, EG in dev but not in production.

Installer

Instructions will be available soon.

Advanced Config

Further examples will be available shortly.

Server

The server accepts a few arguments when starting it from the cli:

--server - Start the server with defaults

--serverport={NUMBER} - Default: 5000 specifies the port the server runs on

--socketPort={NUMBER} - Default: 5050 specifies the websocket port

--delay={NUMBER} - Default: 2000 miliseconds as it takes a moment to handle the files shopify side this allows you to stop reloading before the shopify servers are ready.

Client

The client can be configured to connect to a running server by passing the following paremeters to the initialization function.

socketPortNumber - Default: 5050 - number - port number socketPath - DefaultL ws://localhost - string - url of the server retry - Default: 4000 - number - in milliseconds to retry to connect tot he server

These are used as params passed to the renew function when using the non instantiated version:

window.eight.renew.initRenew(5050, 'ws://localhost', 4000)

this can be usefule to surface the server connection to a tunnel such as ngrok to reloa multiple devices.

Documentation needed.

Formulae & examples

Some examples of advanced usage examples to look at ways to integrate live reloading into almost any ThemeKit theme development work flow. These will be added before this goes to v1

Renew is an Eight Labs project

We are Eight, and we build products for merchants on shopify. We are commited to empowering merchants, and actively supporting the whole Shopify partner eco system, this project is open source and is the first of many we have planned.

Donate a tree to support us

Love using renew ? help us offset the carbon footprint of development, specifically with as large a footprint as commerce and the associated logistics.

Donate a tree https://ecologi.com/weareeightltd

(we are stocked up on coffee! so thought trees were a beter way to support the project.)

Credits

While written from the ground up, it would be off sides to not credit the awesome work by the team at ui-crooks we loved what they did in theme-lab and followed some of their thinking as far as concept and integrationm of reloading.