PicAmaze is an embedded app for animating product images with a complex UI for image processing and animation. While I was waiting it to load into the Shopify Admin panel for the first time I thought ‘I want to get rid of ngrok!’ and make the development process faster. Therefore I share how to develop and run the shopify embedded app on localhost (https://localhost), skip ngrok and embedding into the admin and as a result increase the development speed by getting instant feedback for your changes. Building an interface for a Shopify app that animates images requires a lot of iterations and every delay of development is critical.

When I started coding PicAmaze I was so excited about it that I didn’t sleep for a week. I cloned Node and React Shopify demo app and run it with ngrok (as recommended). However I needed to view my changes immediately. Unfortunately my Internet connection wasn’t fast enough and the large files in development mode made the process painful. So you found two similar ways to avoid waiting.

Run your shopify embedded app on your public IP

With the solution you’ll be able to view and develop your embedded app under https://your-public-ip:port.shopify.

Setup https for your shopify app and expose it to the Internet

To make this work you’ll need:

  1. Public IP or a port visible to the internet and forwarded to your localhost. I recommend using port 443 so you can test your app on a mobile device (iPhone in my case). You need to setup your app in the Shopify partners dashboard with your public IP (both the ‘App URL’ and ‘Allowed redirection URL(s)’)
  2. SSL certificates. You can generate a self signed certificate with the openssl command.
  3. Localhost running over https. To achieve this in Node you can use the following code in your server.js:
Copy to Clipboard

To start your app do the following steps:

  1. Add your public IP to both the ‘App URL’ and ‘Allowed redirection URL(s)’ in your Shopify Partners Dashboard App setup.
  2. Start your server with ‘npm run dev’.

After that open your app from the Shopify Admin panel and you should see your app running way faster than before.

Run your shopify embedded app outside Admin panel

If you want to run your app outside the Shopify admin panel, then you must instruct Shopify App Bridge to disable redirection to the admin panel. To do so edit you _app.js as follows:

Copy to Clipboard

Now you should be able to type in your browser https://your-public-ip:port/auth/inline?shop=xxx.myshopify.com and get your app running. The shop parameter needs to be appended at the end so the oAuth process can be started. In this case I use koa-shopify-auth library.

If you are using Webpack HRM then your changes to the frontend should be applied without restart and significant delay.

For those of you running on Chrome under MacOS and using self signed certificates refer to this solution in case you see the ‘Your connection is not private’ warning. Basically you type ‘thisisunsafe’ with the keyboard and you magically proceed further.

Run Shopify embedded app on localhost

However, public IP or forwarding port are not always available. Therefore, the option is to run and test your Shopify embedded app on localhost. On the other hand, the challenge here is to bypass the oAuth since it requires a public available callback url to pass some internal params. To do that we’ll use ngrok for the oAuth and copy the session cookies to localhost. After that you’ll be able to view and develop you embedded Shopify app on localhost with no need no visit the Shopify admin panel or use ngrok. You need some setup:

Setup ngrok and https for your shopify app

  1. To start with, you need to run your app under HTTPS with ssl certificates (as described above).
  2. Secondly, add your ngrok url to both the ‘App URL’ and ‘Allowed redirection URL(s)’ in your Shopify Partners Dashboard App setup.

Setup ngrok for shopify embedded app

Run the shopify embedded app on localhost

  1. Firstly, start the app using ‘npm run dev‘.
  2. Secondly, start ngrok with ‘ngrok http 3000‘ (use here your http port).
  3. Then, open https://xxx.ngrok.io/auth/inline?shop=yyy.myshopify.com to start oAuth (this is the url if you use koa-shopify-auth).
  4. Moreover, when finished open Site information popup to view the current page cookies.
  5. Further, copy the values of koa.sess, koa.sess.sig and shopOrigin cookies.Copy cookies from ngrok shopify app url after oauth
  6. Continue by opening https://localhost:3001 (or whatever port you are using for https). Then you should be redirected to https://localhost:3001/auth showing error message ‘Expected a valid shop query parameter’.
  7. After that open DevTools -> Application-> Cookies and create koa.sess, koa.sess.sig and shopOrigin cookies with the values from step 3.Create session cookies for shopify embedded app on localhost
  8. At the end navigate to https://localhost:3001 again and you are ready to go.

Take a look at this video to view the process

Unfortunately, I do it every time I’m logged out and I hope I’ll find a faster way to copy cookies soon. For instance, I leave ngrok running all the time so when I need to authenticate it is already there with the same url every time.

Notes on running your shopify app under localhost 

Running on localhost is great. However, remember to test your shopify embedded app in the Shopify Admin panel as well (https://yoursore.myshopify.com/admin/apps/yourapp). Here are two reasons:

  1. Firstly, inside iframe some JavaScript functions behave in a different way (e.g window.location and window.top.location).
  2. Last but not least, the UI looks different when embedded.

Additionally, here is a great tool developed by Shopify to boost developers performance. With it you can populate test data, build UI on the fly and execute 

Finally, I’m very happy with the new token-based authentication coming soon which might make things easier and faster for developers and merchants.