Forem: Red Cap Tom

Shopify App From Scratch #12 - User Interface 2

Red Cap Tom — Sun, 14 Jun 2020 20:43:44 +0000

Deprecation Notice

Yeah, yeah, I know. I hate it too when people abandon tutorial series mid-way. But, due to (exciting!) circumstances, I'm calling it quits for now.

I'm thinking of just dropping a link to the full repo here - it's a mess, but it's something you guys can chew on instead of my empty promises.

If you'd like me to drop it here - let me know at hey@redcaptom.com.

And, just sayin', I had a BLAST doing this. If you know something - anything - about technology, take the time to write it down as a tutorial series. You will get SO, SO much value out of it, you can't even believe it.

Until we meet again - RCT :)

The Video (Scroll down for the article)

Coming soon!

More User Interface

Git repo link

Alright, so we are currently here:

This is nice, but it doesn't actually lets the user choose between the two buttons, now, does it? We'd need to add some sort of input element to allow the user to pick a button variant.

Since this is an OR relation, i.e. you have to pick one - and exactly one - variant of button, a radio button is a great fit. Shopify actually provides us with a Radio Button component that has all sorts of niceties to it:

<RadioButton
  label="The text that appears right next to the button"
  helpText="Greyed-out subtext"
  checked={"A boolean value to indicate whether the button is checked or not"}
  id="An HTML element id, used for selection (must be unique)"
  name="An HTML element name used for identification (can be repeated)"
  onChange={
    "A callback function, that is triggered once the radio button is changed (i.e. marked / unmarked)"
  }
/>

Let's talk a little bit about this, since this is the first time we're observing an element that is not very simple. Look at all the props we're providing the componenet (label, helpText, checked etc.) - I've added a small sentence explaing what each of them does. There are two props - checked and onChange - that get {} as inputs and not just text. Inside those {} we can input whatever JavaScript we want, but they expect to get a boolean and a callback function, respectively. But, hold back one moment. Why do we need a React component for a radio button? We already have <input type="radio">, right? Let's explore this for a second.

A normal radio button (i.e. <input type="radio">) already has a checked attribute and a change event, that can replace the checked and onChange props. We can totally use those without having to wrap the button in a component. But, the Polaris design system would like to standardize the way radio buttons are used in Shopify Apps. Therefore, the RadioButton component encapsulates all the styles Shopify would like you to use with the button (padding, color of the bullet in the button, color of the surroundinc circle etc.). It also allows for a somewhat more convienent wrapper around features that are often used together (like label that removes the need for a <label> tag and helpText that expands the normal label with optional subtext).

The reason why onChange is also a RadioButton property has to do with the way React sees the world. In React, everything is interactive - an action in one element is expected to trigger something in another element, or maybe even in the backend of the application. The change event (in the original <input type="radio">) was created for just this purpose - to be the main source of interactivity for your radio button (when its value changes, do something - i.e. trigger a callback function). But, in practice, getting this functionality of events to work across browsers has been historically hard. React created a new type of event, that "wraps around" the original event, and that is why we have a special onChange property inside the component. This is not the only reason, of course, but to me is the most.... comfortable one. If Dan Abramov ever reads this, and I happen to be wrong (which I sometimes am, it appears) - please accept my sincere apologies and make a comment for me to fix this. :P

Back to business - what do we want to happen when the button changes? Well, we want to first know that it did. Which means we need to store that infomration somewhere. Luckily, we can use state in our App component to keep track of what's going on inside the page!

A Note on Redux

You will note that I, much like the offical Shopify Tutorial, chose to forego the use of a (very) popular JavaScript library called Redux. Redux allows you to have a central, instead of a distributed, location for your state. A state of a component is some information being kept in it about.... whatever, and is notriously difficult to manage as your apps get more and more complicated.

I can honestly say that the app I'm building here is just not complicated enough to justify the use of Redux, or any other central state management library. Therefore, I "bear" the complexity, and choose to manage the state myself. This might seem like I'm doing a lot of hacks to get the information around, but for the sake of simplicity I think it's the way to go.

So before we add the radio button, let's make sure to add state properties that account for which button was selected. For this, I am going to correct an oversight that any experience React developer will tell you I made (albeit intentionally) in the beginning: I omitted the constructor.

A constructor (as I mentioned in the React Sidestep 3) is a special function in a JavaScript class (and specifically inside React class components) that gets called when an object representing the class is initiated. So let's add it first:

class App extends React.Component {
  constructor(props) {
    super(props);
  }
  render() {
    return (
      <AppProvider>
      ...
      </AppProvider>
    );
  }
}

export default App;

VSCode might throw a "useless constructor" error at you (well, probably a warning - i.e. yellow squiggly lines, and not an error). This is OK - this constructor indeed doesn't do anything. All it does is call the constructor of the class above it with the props that were provided to it (since every React class component extends React.Component, its constructor is being called with the pops provided for the current constructor). This is an implementation detail that you shouldn't really care about - it's the way React is built.

The interesting bit comes when we want to provide state to the component. This can happen simply by defining the state attribute for the current class in the following way:

class App extends React.Component {
  constructor(props) {
    this.state = {}
    super(props);
  }
  render() {
    return (
      <AppProvider>
        ...
      </AppProvider>
    );
  }
}

export default App;

We now have a place in our component where we can manage our state. Let's add a property inside our state, one that shows which variant of the button has been selected:

class App extends React.Component {
  constructor(props) {
    this.state = {
      buttonType: "full"
    };
    super(props);
  }
  render() {
    return (
      <AppProvider>
        ...
      </AppProvider>
    );
  }
}

export default App;

We define buttonType to be "full" upon initialization to provide some sort of default to the user. This means that at first initizliation, the selection box will be the one one with the full button in it. In the future, we will have this value stored in a database, and brought into the application to "remember" the prefence of the user. More about this later.

We also need to create some function that - when the button's status is changed - chages the value in the state of the component. This is a function that is called when onChange is called on RadioButton - i.e. a callback fucntion. Let's call this function handleButtonTypeSelection, since it handles which type of button is used.

This function can go in one of one of 4 places, which can cause a bit of confusion. I'm choosing to add them as arrow functions inside the render function, like so:

class App extends React.Component {
  constructor(props) {
    this.state = {
      buttonType: "full"
    };
    super(props);
  }
  render() {
      const handleButtonTypeSelection = (changedButtonType) => {
    ...
  }
    return (
      <AppProvider>
        ...
      </AppProvider>
    );
  }
}

export default App;

I like this option because it feels, to me, like it's simpler once you figure out how arrow functions work like. For most intents and purposes, an arrow function is just another way to write a function - instead of funcName(){}, we're writing const funcName = () => {}. But, there are some places where the arrow function behaves a bit differently than your run-of-the-mill function - and I will warn you about them as they come up. In this case - use the arrow! :)

Our full function needs to accept the type of button that was selected, and change the state of the component's buttonType accordingly. As you will see in a moment, this will also check the correct button by changing the checked prop on each RadioButton component. Let's put our full function in then:

class App extends React.Component {
  constructor(props) {
    this.state = {
      buttonType: "full"
    };
    super(props);
  }
  render() {
      const handleButtonTypeSelection = (changedButtonType) => {
        this.setState({ buttonType: changedButtonType });
  }
    return (
      <AppProvider>
        ...
      </AppProvider>
    );
  }
}

export default App;

This part:

this.setState({ buttonType: changedButtonType });

Changes the value of buttonType in the state of the component. Specifically, what it's doing is passing a destructured object into the setState function (which, as you probably guessed, sets the state). Destructuring is a totally awesome (and rather new) concept in JavaScript, that basically allows you to unpack properties from objects, and treat them as simple variables. The statement above, therefore, is exactly like doing:

const newState = {
  buttonType: changedButtonType;
}
this.setState(newState)

But the destructuring just saved me an unneccessary variable declaration.

Back to business - we now have our callback function, but still missing our RadioButton components. Let's finally put them in, and get the following:

import React from "react";
import { Page, AppProvider, Layout, Card, RadioButton } from "@shopify/polaris";
import "@shopify/polaris/styles.css";

class App extends React.Component {
  constructor(props) {
    super(props);
    this.state = {
      buttonType: "empty",
    };
  }

  render() {
    const handleButtonTypeSelection = (changedButtonType) => {
      this.setState({ buttonType: changedButtonType });
    };
    return (
      <AppProvider>
        <Page
          title="Welcome!"
          subtitle="Please select the type of button you'd like to generate for your site:"
        >
          <Layout>
            <Layout.Section oneHalf secondary>
              <Card title="Black Button Variant" sectioned>
                <Card.Section title="Demo">
                  <button>Dummy Full Button</button>
                </Card.Section>
                <Card.Section>
                  <RadioButton
                    label="Choose Full Button"
                    helpText="Works well with the default Shopify themes and lighter backgrounds."
                    checked={this.state.buttonType === "full"}
                    id="full"
                    name="full-button"
                    onChange={() => handleButtonTypeSelection("full")}
                  />
                </Card.Section>
              </Card>
            </Layout.Section>
            <Layout.Section oneHalf>
              <Card title="Empty Button Variant" sectioned>
                <Card.Section title="Demo">
                  <button>Dummy Empty Button</button>
                </Card.Section>
                <Card.Section>
                  <RadioButton
                    label="Choose Empty Button"
                    helpText="Works well with darker backgrounds, to create a high-contrast feel."
                    checked={this.state.buttonType === "empty"}
                    id="empty"
                    name="empty-button"
                    onChange={() => handleButtonTypeSelection("empty")}
                  />
                </Card.Section>
              </Card>
            </Layout.Section>
          </Layout>
        </Page>
      </AppProvider>
    );
  }
}

export default App;

Which should render like so:

Try checking and unchecking both RadioButtons, and observe that only one of them can be checked at any given moment. This is due to each of them pulling its checked prop from the value of the buttonType state property.

That's enough for today, I think. :) We covered a lot of not-strictly-related ground, but I think it was a good detour into JavaScript and the cool features it has to offer.

An Offer

If you're working on a Shopify app, and your app uses Polaris for the front-end, I want to hear from you. I am willing to sit down and run a debug session / add a new feature with you for your application, if you agree to stream it live with me (or record it and publish it later). It's not easy writing a full-stack JS app, doubly so when you're not from within the ecosystem. Let's do it together and help all the people! :)

E-Mail me at hey@redcaptom.com, and let's set it up.

Shopify App From Scratch #11 - User Interface 1

Red Cap Tom — Sat, 13 Jun 2020 08:48:34 +0000

Deprecation Notice

Yeah, yeah, I know. I hate it too when people abandon tutorial series mid-way. But, due to (exciting!) circumstances, I'm calling it quits for now.

I'm thinking of just dropping a link to the full repo here - it's a mess, but it's something you guys can chew on instead of my empty promises.

If you'd like me to drop it here - let me know at hey@redcaptom.com.

Until we meet again - RCT :)

The Video (Scroll down for the article)

Coming soon!

Building the User Interface

Alright, we're finally here - it's time to get building!

If you follow the official tutorials, the way Shopify teaches you how to build apps revolves around the backend first, and the frontend later. I take a different approach, mostly for the sake of speed of iteration (it's much faster to mock a backend in order to build a frontend, than it is to mock a frontend in order to build a backed IMHO). Another advantage is that you don't end up writing useless backend routes that never gets called - once the interface is all lined up, it's clear what needs building on the backend.

Getting ready

From now on, every line of code will go into a Git repository, with every post in the series represented as a commit. This is to allow you to follow along as I do my thing, and so you can revert back (more on this later) if you get stuck somewhere along the way.

Note that the link I post here is to the tree of the relevant commit. This might sound complicated, but I'd like to assure you that it's not - it's a feature of Git exposed by Github. All that means from your perspective is that the state of the repository in that link - i.e. the files you will see - match the state of the repository when I wrote this tutorial. Here is the state of the repository for this tutorial.

If you need further explanation - please let me know!

a Note About the Terminal

It's probably obvious by now that I'm not using Windows for these tutorials. I'd really like to be able to contribute more to the Windows-folk out there (I assume you guys are the majority here), and if you recall I tried to give Windows alternatives when unix tools were unix-only (read: nvm-windows). If at any point you're not sure which command is which in Windows, just email me at hey@redcaptom.com and I'll edit the information in.

Recall our previous mockup:

We will now attempt to recreate it in React and Shopify Polaris. Let's first get the correct node version (we'll use the LTS version which is 12.18.0 at the time of writing - this version will be supported for a long while from now). For that we'll need nvm, which you can get from here.

This makes sure we will have the correct version added to source control, allowing anyone who uses the project to use the same Node.js version that we do.

nvm install 12.18.0 && \
nvm use 12.18.0

From here on we have two options: We either roll our own project scaffolding, or we use a scaffolding tool to do the work for us. Remember - this is not the final version of our app, which will use Next.js as the main backbone. This is just an experimentation playground - one step removed from all the complexity - where we can build our React & Polaris interface in an isolated way, away from the full app.

For that purpose, then, we will use create-react-app that we've seen in the React sidestep, add Polaris to it and voila - we're good to go!

cd ~ && \
npx create-react-app countries-we-ship-to-button && \
countries-we-ship-to-button

Wait for that bad boy to finish, and you will find yourself inside the project folder.

In order to begin work on the interface, we're going to need Shopify Polaris:

npm install @shopify/polaris

Ignore any warnings that come by - we're using a very mainstream package with great support. If something does not work out of the box in this stage - it's probably not the package's fault.

By the way - that @ there, in @shopify/polaris? That's called a "Scoped NPM Package", and it means that this is an official module from Shopify. Goodie! :)

Starting For Real Now

Let's dive in! The scaffolding that create-react-app does allows us to use App.js for experimentation - everything is loaded up and ready to go. Your App.js should look like this:

import React from "react";
import logo from "./logo.svg";
import "./App.css";

function App() {
  return (
    <div className="App">
      <header className="App-header">
        <img src={logo} className="App-logo" alt="logo" />
        <p>
          Edit <code>src/App.js</code> and save to reload.
        </p>
        <a
          className="App-link"
          href="https://reactjs.org"
          target="_blank"
          rel="noopener noreferrer"
        >
          Learn React
        </a>
      </header>
    </div>
  );
}

export default App;

And we can get going. Let's first turn the functional component into a class component, since this component is going to be rather large, and I prefer to have my larger components as classes and my smaller ones as functional components:

import React from "react";

class App extends React.Component {
  render() {
    return (

    );
  }
}

export default App;

We can now import Polaris (note how we're importing both the library and they style files - this is just because we're playing with the interface here manually, and will be abstracted away once we move over to Next.js), and specifically the <Page> component, which will be the first Polaris component we use:

import React from "react";
import { Page } from "@shopify/polaris";
import "@shopify/polaris/styles.css";

class App extends React.Component {
  render() {
    return (
      <Polaris.Page
        title="Welcome!"
        subtitle="Please select the type of button you'd like to generate for your site:"
      ></Polaris.Page>
    );
  }
}

export default App;

Let's run our code, to see how it looks like live! Type the following into your terminal:

npm start

And you should see the following error message:

This is perfectly fine, and has to do with how Shopify apps are expected to be built. Shopify has a special component called AppProvider that wraps all Shopify apps, allowing all the components in the app to share a set of properties across the board. Don't fuss too much about it right now - we'll deal with it later. For now, just add it to your code to make sure you pass the check:

import React from "react";
import { Page, AppProvider } from "@shopify/polaris";
import "@shopify/polaris/styles.css";

class App extends React.Component {
  render() {
    return (
      <AppProvider>
        <Page
          title="Welcome!"
          subtitle="Please select the type of button you'd like to generate for your site:"
        ></Page>
      </AppProvider>
    );
  }
}

export default App;

You should now see the following:

Which means that Polaris is properly installed, and we have created our first page!

We'd like to now create a proper layout for our page. Fortunately, Polaris provides the Layout component to let us scaffold the page properly. Let's add it now to create two half-sections for our page, just like in the schema we drew up before:

import React from "react";
import { Page, AppProvider, Layout } from "@shopify/polaris";
import "@shopify/polaris/styles.css";

class App extends React.Component {
  render() {
    return (
      <AppProvider>
        <Page
          title="Welcome!"
          subtitle="Please select the type of button you'd like to generate for your site:"
        >
          <Layout>
            <Layout.Section oneHalf>
              <h1>First Half</h1>
            </Layout.Section>
            <Layout.Section oneHalf>
              <h1>Second Half</h1>
            </Layout.Section>
          </Layout>
        </Page>
      </AppProvider>
    );
  }
}

export default App;

You should now see something like this:

Note that the Layout component has a sub-component called Section. This is what the Layout.Section syntax means - it's a component within a component. Specifically, since a component is actually a function, Section is a property of that function, that just happens to be another function. An in React-speak, this is a component nested inside another component.

Note also the oneHalf property (i.e. 'prop') we gave the Layout.Section component - this is one variant out of a few (see here) that we can give the section to form a "grid" of sorts on the page. This is useful if you'd like to have columns in your page (created by multiple Sections in the same Layout, each with a oneHalf or oneThird property supplied to it).

But this is still not a great look, since the headers are kind of "floating" in the page. Let's wrap them in a Card component, shall we?

import React from "react";
import { Page, AppProvider, Layout, Card } from "@shopify/polaris";
import "@shopify/polaris/styles.css";

class App extends React.Component {
  render() {
    return (
      <AppProvider>
        <Page
          title="Welcome!"
          subtitle="Please select the type of button you'd like to generate for your site:"
        >
          <Layout>
            <Layout.Section oneHalf>
              <Card title="First Half"></Card>
            </Layout.Section>
            <Layout.Section oneHalf>
              <Card title="Second Half"></Card>
            </Layout.Section>
          </Layout>
        </Page>
      </AppProvider>
    );
  }
}

export default App;

It should now look like this:

Let's add some content into our cards, by sectioning it out - this will later act as a menu from which the customer can choose which type of button they'd like to have in their website. That way, the content of each selection will be a demo of one variant of the button (we will actually implement that button later, so I'll use a dummy one for now). Note that this is similar in nature to Sectioning out the Layout interface like we did before:

import React from "react";
import { Page, AppProvider, Layout, Card } from "@shopify/polaris";
import "@shopify/polaris/styles.css";

class App extends React.Component {
  render() {
    return (
      <AppProvider>
        <Page
          title="Welcome!"
          subtitle="Please select the type of button you'd like to generate for your site:"
        >
          <Layout>
            <Layout.Section oneHalf>
              <Card title="Full Button Variant">
                <Card.Section title="Demo">
                  <button>Dummy Full Button</button>
                </Card.Section>
              </Card>
            </Layout.Section>
            <Layout.Section oneHalf>
              <Card title="Empty Button Variant">
                <Card.Section title="Demo">
                  <button>Dummy Empty Button</button>
                </Card.Section>
              </Card>
            </Layout.Section>
          </Layout>
        </Page>
      </AppProvider>
    );
  }
}

export default App;

And I think this is enough for this post. We now have a working playground to play with, as well as a start to our product page! Stay tuned for the rest of the interface in the upcoming tutorials.

Shopify App From Scratch #10 - Shopify Polaris

Red Cap Tom — Sat, 06 Jun 2020 17:32:37 +0000

Deprecation Notice

Yeah, yeah, I know. I hate it too when people abandon tutorial series mid-way. But, due to (exciting!) circumstances, I'm calling it quits for now.

I'm thinking of just dropping a link to the full repo here - it's a mess, but it's something you guys can chew on instead of my empty promises.

If you'd like me to drop it here - let me know at hey@redcaptom.com.

Until we meet again - RCT :)

The Video (Scroll down for the article)

Coming soon!

Introduction

When you're building a large collection of independent components across a large enough team, people are going to have opinions about how to design each part of the system. This, in and of itself, is not a bad thing - product managers, engineers and designers should all pitch in on the look and feel of the system to provide a holistic perspective of what's desired, what's possible and what's most awesome-looking. But there are some thing that should remain consistent across the entire stack - the colors of buttons, the fonts, the look and feel of tables, the general padding and margin and borders of elements, etc.

A while back, there was no proper name for this desired "universalism" across the front-end part of software projects. At some point, most likely around the arrival of component-based frameworks (read: React), it became apparent to some of the largest software players in the world that having a universal design language for their products is probably a good idea. Some examples include Google's Material Design, GitHub's Primer and MailChimp's Patterns.

What's in a design system?

Most modern design system consist of multiple components, which can be divided roughly into two parts:

Visual Guidelines - Instructions on what colors, typography, language, spacing etc. to use in the software.
Components - A set of often-used components that embody those visual guidelines, written in a widely used framework (React is a often a prime candidate, but you might see Vue.js or plain HTML components as well).

In the video I focus a bit more on the visual guidelines, but in this post I'll deal mostly with the components.

Why should you care?

Generally speaking, if you're building a software product as part of another software company's ecosystem, and your product is intended to complement said company's product - you'll do well to comply with their design system. It will cause your product to integrate into the platform better, will save you the trouble of making a lot of design decisions and will often also save you quite a bit of time.

This goes double for products that are directly embedded into another piece of software - like Shopify apps. There are a lot of apps out there that use their own styles (usually Bootstrap) which just looks.... bad.

If you're building something to delight your users, and you're part of a larger ecosystem - you should either conform (if the outer styles are good) or differentiate (if the outer styles are the worst). In this case, Shopify really made a good design move, and I'd offer you to conform to their standards (and, to be honest, it does not hurt your chances of getting your app approved).

Shopify Polaris - Shopify's Own Design System

Polaris is Shopify's own foray into the design system game, and I will focus specifically on polaris-react - the React-based, Polaris-compliant component set.

First and foremost, it's important to note that the components we're going to see here look a little differently than the ones we've seen before. This is because they are not written in simple JavaScript, but in a superset of JavaScript called Typescript. What is a superset, you may ask? It's a set, that contains another set, and then some. What, you may rightfully ask, are you talking about? Doesn't matter. For the sake of this discussion, TypeScript is Javascript - with types. Fun to be had by all!

Seriously though, the only reason I'm even mentioning this is because I want you to understand that Polaris is not really anything new - it's just a bunch of components neatly wrapped up in a package. You should be able to re-create them yourself if you so please, not to mention be able to understand them. However, like in the case with React, I think it serves us to observe what they look like in the wild. To that end, I will take a look at two different components, one simple and one a bit more complicated and got a bit into depth on how they're built and how to use them.

Example Component - Button

The "Hello World" of Polaris is, in my opinion, the button:

Polaris Docs - Button
GitHub Repo - Button

Consider the directory structure of that button (located at https://github.com/Shopify/polaris-react/tree/master/src/components/Button ):

# Button

* [tests/](./Button/tests)
  + [Button.test.tsx](./Button/tests/Button.test.tsx)
* [Button.scss](./Button/Button.scss)
* [Button.tsx](./Button/Button.tsx)
* [README.md](./Button/README.md)
* [index.ts](./Button/index.ts)
* [utils.tsx](./Button/utils.tsx)

This feels like a lot of stuff for a button, right? Let's break it down:

tests - React components are, by definition, individual units of code that structure an application's UI. They are the atomic bits of your user interface, and by popular opinion should be tested individually before being combined together. It's therefore common to create tests for each component separately, and then bundle those tests in proximity to the component. This allows users to pick-and-choose the components they like, and still have unit tests available for the taking immediately. These tests are written (in Polaris's case) using a testing framework for JavaScript called Mocha, originally written by the ever-awesome TJ Holowaychuk. If you're reading this, dear TJ - we love you here in JS land. You the bomb.
Button.scss - There a few different ways of styling React components, and in this specific case the Shopify staff chose to use a preprocessor (Sass). Sass is similar to CSS in some ways, and is looked at as a CSS "extension language" - you have a bit more flexibility in defining your styles, and they take care of translating the Sass syntax into proper CSS. Since we will not be using Sass, I will not say anything further about it (I will mention, however, that it is one of those things I have very little knowledge about but always wanted to dive into deeper).
Button.tsx - The TypeScript-React file is actually a combination of two types of files - .tsx stands for TypeScript ( ts ) - with the possibility to embed JSX - ( x ). Recall that JSX is what I referred to as "HTML On Steroids" - it's what your functional components return, that end up constructing the virtual DOM. If you take a deep dive inside, you'll see that it's quite a long file (350+ lines at the time of writing), which sounds a little bit surprising given that it's just a button. But, if you look closely at the Polaris docs, you'll see that this innocent button actually has 17 different possible configurations - all accessible by adding various in-tag attributes (i.e. React props) to the button:

That's where Button.tsx comes in - it's all about the props that you pass into the button, whose mixture configures how the button will look like.

README.md - Just a README file.
index.tx - This is just an export file - it ensures everything inside this folder is accessible to files from the outside. Unless you're super into the way JS projects need to be structured due to.... reasons, then this is just a detail and nothing else.
utils.tsx - This file contains functions that help use the Button component from elsewhere. You will see this in action in the next section.

All of those files eventually make, for example, this:

<Button primary>Save theme</Button>

Into this:

Which is not that much, right? Well, that's until you see that very same component as part of another component, and then everything starts to make a little more sense.

Example Component - Callout Card

The beauty of Polaris, and actually React in general, is the fact that most things are re-used in some form or another in other things. In a more formal manner, a hybrid component is a component that's composed of other components - exposing only the top-most component for you to interact with.

It makes little sense for you to re-implement a button each time you need one, and doubly so if you'd like for the buttons to remain consistent across all your components. The Callout Card is component that combines a button inside of it, but you don't actually need to write <Button> anywhere yourself - the component takes care of this for you.

Polaris Docs - Callout Card
GitHub Repo - Callout Card

This is how it looks like:

See the button there? It's actually created in the CalloutCard.tsx file:

  const primaryActionMarkup = buttonFrom(primaryAction);

And remember the utils.tsx file from the Button component? It actually contains this buttonFrom(action) funtion:

export function buttonFrom(
  {content, onAction, ...action}: ComplexAction,
  overrides?: Partial<ButtonProps>,
  key?: any,
) {
  return (
    <Button key={key} onClick={onAction} {...action} {...overrides}>
      {content}
    </Button>
  );
}

That, unsurprisingly, creates a button out of some action , which is an abstraction of whatever it is you'd like the button to do - throw up a pop-up, call some long-running task, delete something, refresh the page etc.

Let's look at the code for the CalloutCard this time, and actually observe how we can customize it. This is how the default CalloutCard looks like when you want to use it on your front-end:

<CalloutCard
  title="An Awesome TItle"
  illustration="Some_Illustation_From_Undraw.svg"
  primaryAction={{
    content: 'Button Text',
    url: 'http://SomeLink.com',
  }}
>
  <p>Your Awesome Callout Card Text</p>
</CalloutCard>

So you are able to customize the following options of the card:

title - The main piece of text the card promotes.
illustration - Some illustration to be placed in a strategice location in the button (see how that strategic placement is abstracted away from you? This is not a mistakle, but good design by the Shopify people). BTW, unDraw is this awesome project by the very talented Katerina Limpitsouni, that aims to provide programmers with great, royalty-free and actually-free illustrations. You will see that I try to use it whenever I can in my projects, since her illustrations resemble Shopify ones visually, and have the same color scheme.
primaryAction - An object to define what the button is there to "Call Out" for you to do:
- content - The call to action, i.e. the text of the button.
- url - The URL to access when the button is pressed. This doesn't actually have to be a URL, and can be swapped for action to perform some in-app operation (like calling a function).

I think that's enough for Polaris - there's so much to go into, and I hope in the future to do a "Quick Hits" type series, talking and giving actual working examples of every Polaris component in production. For now, though, that should be enough to give you a feel for Polaris. Moving on!

Shopify App From Scratch #9 - React Sidestep 3

Red Cap Tom — Sat, 06 Jun 2020 17:10:55 +0000

Deprecation Notice

Yeah, yeah, I know. I hate it too when people abandon tutorial series mid-way. But, due to (exciting!) circumstances, I'm calling it quits for now.

I'm thinking of just dropping a link to the full repo here - it's a mess, but it's something you guys can chew on instead of my empty promises.

If you'd like me to drop it here - let me know at hey@redcaptom.com.

Until we meet again - RCT :)

The Video (Scroll down for the article)

Coming soon!

React class components

Introduction

Generally speaking, you can get along in most simple React applications by just using functional components. If you need to keep some data that changes over the runtime of the application, for example, you can use the useState hook. If you need to do something when a component was added, removed or updated from the application then you can use the useEffect hook.

But, before React 16.8 (which was released in February 2019), hooks were not even a thing. They became available only after that release, meaning that before February 2019 you could not have state in a functional component, or know that it has mounted or unmounted. In practice, you used functional components for the "simple" stuff, and class components for the "complicated" stuff.

This is obviously no longer the case, but I still enjoy thinking in those terms. It offers perspective on what tools are correct for each job, and prevent you from over-complicating things with class components when you can just functionalize (is that a word?) your way to glory.

Class Components Are Heavyweights

Class components are, from my perspective, a more heavyset version of functional components. They offer more fine-grained control over the component and are great as wrappers of functional components, but come at the price of more verbosity, a higher learning curve and less syntactic sugar than functional components. Let's take a look, shall we?

A note about classes in JavaScript

I have to add quick note on what a class actually is in JavaScript land: it's just a wrapper around existing JavaScript ideas, presented in a way that will appeal to Object-Oriented programmers. Put plainly - JS Classes are a way to define what a thing is, and then create occurrences of that thing in your application.

This means that you can define that class once, and then use it (the correct term is "instantiate" it) anywhere else in your application. In practice, we do not do that directly in React - you do not instantiate the class component you create: React does that for you when it mounts the component. You can re-use the component in many places in your application, sure, but you can also do that with functional components, right?

This is confusing, and actually not very relevant if all you're trying to get is a grip on how React looks like so you can pick up its ideas as you go along. For the sake of our discussion, then, I'm going to drop all reference to the JS concept of a class, and focus instead on React class components only. If you're still interested, dive into the docs - they're really good.

How Does One Identify A React Class Component In The Wild?

The General Structure

Excellent question. I'm going to take an example from the official React docs and explain a little bit more on each part then they do there (although, if you come from an Object-Oriented background, you probably already know most of what I'll talk about):

class Clock extends React.Component {
  constructor(props) {
    super(props);
    this.state = {date: new Date()};
  }

  render() {
    return (
      <div>
        <h1>Hello, world!</h1>
        <h2>It is {this.state.date.toLocaleTimeString()}.</h2>
      </div>
    );
  }
}

ReactDOM.render(
  <Clock />,
  document.getElementById('root')
);

This class renders a clock that displays the current hour in HH:MM:SS format to a page. Let's break it piece by piece, starting first with the virtual DOM rendering:

ReactDOM.render(
  <Clock />,
  document.getElementById('root')
);

We've seen this before, this is how we place components on the DOM. Let's disregard it, since placing components on the virtual DOM is the same in functional and class components. Removing it, then, leaves us with:

class Clock extends React.Component {
  constructor(props) {
    super(props);
    this.state = {date: new Date()};
  }

  render() {
    return (
      <div>
        <h1>Hello, world!</h1>
        <h2>It is {this.state.date.toLocaleTimeString()}.</h2>
      </div>
    );
  }
}

The Breakdown

The first part of the component is its definition - class Clock extends React.Component. This just means we're using an existing thing from React - the Component class - as the basis for our class. This allows use to create our class by basing it on a set of features React offers in the Component class. Moving on:

  constructor(props) {
    super(props);
    this.state = {date: new Date()};
  }

A constructor is a special function that is called when the class is instantiated - in our case, when the component is evaluated by React before being placed on the DOM. The props are the attributes we've seen passed to components in the previous example - e.g. in <MainInfo participantName="tom"/>, the MainInfo component's participantName prop has the value tom. The reason we're passing the props to the constructor is so we can have access to them inside the component - otherwise we will not be able to know that participantName had the value tom when the component is mounted, making it difficult for us to display it on the page, for example.

super(props) is another special function that calls the constructor of the upper class our class is extened from - i.e. React.Component. We do that to make sure the concept of props works correctly in our class component, as explained here.

Finally, this.state = {date: new Date()} can be formatted a bit differently for better legibility:

this.state = 
{
    date: new Date();
}

Which means we're assigning this - i.e. our class Clock - a property called state (yes, like in the useState() hook), that is a JavaScript Object that contains a single field date. We then set this field to contain the current date (new Date() returns the current date and time). So, what we're basically doing is initializing the state of the object with a single element - the current time.

This is a common pattern in class constructors. We can then change the state by calling a special function called setState() (more about it here - it works like the handler function from useState() we've seen in the previous section), and access any elements in the state of the class by using this.state.X (like in our example - more on this below).

Moving on:

render() {
    return (
      <div>
        <h1>Hello, world!</h1>
        <h2>It is {this.state.date.toLocaleTimeString()}.</h2>
      </div>
    );
  }

This part determines what the component does - i.e. how it looks like when rendered. The render() and return() parts are just React's way of saying - this is how the component is going to look like when presented. The interesting part is the JSX (we talked about it previously) between the parantheses of return():

      <div>
        <h1>Hello, world!</h1>
        <h2>It is {this.state.date.toLocaleTimeString()}.</h2>
      </div>

This is what the component is going to actually look like - two headers, the first of which is static and the second one referencing the date element in our state. Specifically, we'd like to extract the time in the user's time zone, which is what date.toLocaleTimeString() does.

Phew, that was a bit long, but I hope you got a good sense of what a class component looks like in practice. I'd like to make just a final note on lifecycle methods and nip this in the bud:

The React Component Lifecycle

We are going to add one small thing to our class component - a lifecycle method:

componentDidMount() {
    console.log("Clock has mounted, dude!");
}

So our full component is:

class Clock extends React.Component {
  constructor(props) {
    super(props);
    this.state = {date: new Date()};
  }

componentDidMount() {
    console.log("Clock has mounted, dude!");
}

  render() {
    return (
      <div>
        <h1>Hello, world!</h1>
        <h2>It is {this.state.date.toLocaleTimeString()}.</h2>
      </div>
    );
  }
}

All this does is log a message in the console when our clock component is being added to the DOM (i.e. when it is mounted). These type of methods allow us to have a finer control of what happens when our component's status changes. Why is this useful, you ask? To me, it's kinda tricky to explain this out of the context of a full application. We will see an example of this being used in the final application I'm building in this series, but for now it's enough to say that it's really convenient to be able to know when a component has entered and left the DOM.

Final words

This is all I have to say about React itself in the context of this tutorial. This is only the tip of the iceberg, as React is a somewhat advanced framework - but should give you at least some intro into what it is you're looking at when reading React code. I do recommend you go buy Dave Ceddia's Pure React - it taught me most of what I use in my apps, and the guy is still updating it today! Hey Dave, if you're reading this, thank you for an awesome book! :)

Shopify App From Scratch #8 - React Sidestep 2

Red Cap Tom — Sat, 06 Jun 2020 17:05:27 +0000

Deprecation Notice

Yeah, yeah, I know. I hate it too when people abandon tutorial series mid-way. But, due to (exciting!) circumstances, I'm calling it quits for now.

I'm thinking of just dropping a link to the full repo here - it's a mess, but it's something you guys can chew on instead of my empty promises.

If you'd like me to drop it here - let me know at hey@redcaptom.com.

Until we meet again - RCT :)

The Video (Scroll down for the article)

Coming soon!

A Short Primer

Before we dive into it, It's important to note that React is just JavaScript. Facebook wrote React as a JavaScript library that deals with scaffolding up the front-end part of a website. This means that you should probably know some JavaScript before you enter this sidestep. If you don't know any javascript, as in you've never written a line of it, go do a tutorial and come back.

Keep in mind that this is just a sidestep - it's not actually a tutorial. It's something that is done in order to familiarize you with the concepts that I'm talking about, so when you look at a syntax or when I'm running through the application we're going to build, you have some idea of what I'm talking about. It's not meant to teach you React - it's just meant to give you a taste of it, and maybe give you some terms you can later Google and dive into properly.

Before we actually install React and play with it a bit, I do want to mention one thing. React, by itself, has two "worlds" in it. The first one, what people usually talk about when they talk about React, is JSX - which is what React components are returning - which kind of looks like HTML and not really like JavaScript. This can be confusing to people. What you should know is React is kind of half-and-half in that sense - one part is what you return to the page (JSX) and a second part is in charge of what, where and when the former JSX gets thrown up on the page.

This is a bit "in the air", and therefore I'd like to dive in and explain as I go along.

Setting up

Given that React is a JavaScript framework, we will use stuff from the JavaScript ecosystem. Specifically, if you come from a a PHP or ASP or those kind of languages, you're used to spinning up a server and putting your stuff there in order to see them run.

If you're on Windows it's probably XAMPP, if you're on a Mac it's probably MAMP and if you're on Linux you probably roll your own configuration. Anyways, what you probably do is running a server (i.e. Apache), putting files in the exposed folder in that server (i.e. htdocs or www) and then serving those files from there by opening your browser to that location.

The JavaScript frameworks usually have a bundled-in server which is very similar to running XAMPP locally, except for the fact that the framework takes care of everything for you.

This is a theme that will become more and more apparent as you dive deeper and deeper into JavaScript frameworks. They have a tendency to do everything for you - lots of packages, lots of stuff out there to save you time and headaches. Everything you can think of - from testing to linting to deploying to... you name it - they have it. This makes the entire "getting started" phase of a project really really fast.

We're going to dive right in. First things first - let's make sure we got the correct version for the project in front of us. This can be done using nvm - Node Version Manager - which we have installed previously. The command nvm use tells nvm to "switch the context" to the correct version of Node. I used V12.13.1 of Node for this project, so we can do:

nvm use 12.13.1

To get the correct version for this project, and you should see a success message telling you that you are now using the correct version. If you don't have that version installed, just do:

nvm install 12.13.1

Scaffolding the project

To get it. We're now going to use npx - which is kind of like a sister tool to npm - that is used to run executables in packages. The actual stuff going on behind the scenes don't really matter right now - it is just used for installation of a scaffolding tool for React called create-react-app. It feels like a build tool for React but that's not really what it does - a better term for it will be a "Scaffolder", so that's what I'm going to use. Run the following to create a new project called react-sidestep, since that's what we are doing right now:

npx create-react-app react-sidestep

It's gonna take a while. If you watch the video, I go most of what the script installed. I think it's a great overview for what is available out of the box with this scaffolding tool.

Note that this created a new folder in the directory you were in called react-sidestep. Go into it by running:

cd react-sidestep

we can now actually run our newly-scaffolded React app by doing:

npm start

And see the following screen pop up in front of us:

You might note that there are a bunch of files in that folder - see the video for an exact breakdown of what each of the files is actually all about. I also go quite deeply into the JavaScript ecosystem, npm and various interesting things around developing in modern JavaScript.

In Comes React

But, let's get down to business - how React actually looks like in the wild. Let's take a look at the src folder:

src
--| App.css
--| App.js
--| App.test.js
--| index.css
--| index.js
--| logo.svg
--| serviceWorker.js
--| setupTests.js

The entry point to the app - and the interesting tidbit from our end - is index.js, so this is what I'm going to focus on:

import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import * as serviceWorker from './serviceWorker';

ReactDOM.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
  document.getElementById('root')
);

// If you want your app to work offline and load faster, you can change
// unregister() to register() below. Note this comes with some pitfalls.
// Learn more about service workers: https://bit.ly/CRA-PWA
serviceWorker.unregister();

Let's break it bit by bit - the first thing you see is the imports:

import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import * as serviceWorker from './serviceWorker';

Those imports are either coming from the node_modules folder (i.e. were installed in by definition in the package.json file and/or by npm install <package>), or local files. You can separate the two by the ./ before local files, whereas npm packages just have the package name as the origin of the import.

So react and react-dom are both both packages that are inside the node_modules folder, whereas everything else is originating in some local folder or file inside our project.

The interesting part comes now:

ReactDOM.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
  document.getElementById('root')
);

React doesn't actually populate HTML tags into your page. What React does is simulate a DOM - the representation of things on a web page - and maintains it completely independently of the actual DOM you see on the page. That DOM is called a Virtual DOM, and it is the best mapping React can create to simulate the behavior you expect to see on a page.

In order to actually understand what this means, let's skip over to the public/index.html file for a second:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="theme-color" content="#000000" />
    <meta
      name="description"
      content="Web site created using create-react-app"
    />
    <link rel="apple-touch-icon" href="%PUBLIC_URL%/logo192.png" />
    <!--
      manifest.json provides metadata used when your web app is installed on a
      user's mobile device or desktop. See https://developers.google.com/web/fundamentals/web-app-manifest/
    -->
    <link rel="manifest" href="%PUBLIC_URL%/manifest.json" />
    <!--
      Notice the use of %PUBLIC_URL% in the tags above.
      It will be replaced with the URL of the `public` folder during the build.
      Only files inside the `public` folder can be referenced from the HTML.

      Unlike "/favicon.ico" or "favicon.ico", "%PUBLIC_URL%/favicon.ico" will
      work correctly both with client-side routing and a non-root public URL.
      Learn how to configure a non-root public URL by running `npm run build`.
    -->
    <title>React App</title>
  </head>
  <body>
    <noscript>You need to enable JavaScript to run this app.</noscript>
    <div id="root"></div>
    <!--
      This HTML file is a template.
      If you open it directly in the browser, you will see an empty page.

      You can add webfonts, meta tags, or analytics to this file.
      The build step will place the bundled scripts into the <body> tag.

      To begin the development, run `npm start` or `yarn start`.
      To create a production bundle, use `npm run build` or `yarn build`.
    -->
  </body>
</html>

Specifically, take a look at this part:

    <div id="root"></div>
    <!--
      This HTML file is a template.
      If you open it directly in the browser, you will see an empty page.

      You can add webfonts, meta tags, or analytics to this file.
      The build step will place the bundled scripts into the <body> tag.

      To begin the development, run `npm start` or `yarn start`.
      To create a production bundle, use `npm run build` or `yarn build`.
    -->

This basically explains the whole thing - React takes care of maintaining some representation of the optimal DOM somewhere in memory, and then adds / remove HTML elements from the page accordingly. Specifically, you can tell it to start adding/removing elements from a specific place in the page, and the most common location to do that is an HTML <div> element with the id of root. Back to our JavaScript for a second:

ReactDOM.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
  document.getElementById('root')
);

It might make a bit more sense to you now - we're telling ReactDOM to "render" - i.e. throw on the page - something that looks like three HTML tags (but is actually JSX, and we'll talk about that in a second), and then place them inside the root HTML element. This, in essence, means that React will "push" into the <div> whatever it is we ask it to push, and in our specific case it will push:

  <React.StrictMode>
    <App />
  </React.StrictMode>

Under the root element. Note that this is very different than what you might be used to - it's, conceptually at least, "offloading" the creating of the webpage to React. I think it's a great abstraction over what I was previosuly used to, but that's of course up for debate:)

Funcational Components

So what is this mystical JSX that I keep on talking about?

Well, in essence - it is JavaScript. It is a "syntax extension" - which is a fancy way of saying "let's add more words to our language's dictionary" - that allows us to use actual logic when creating our interfaces.

You can have functions, variables, conditionals and other fun things you're used to from your favorite programming langugaes right in JSX - enabling you to refrain from mixing-and-matching PHP, JavaScript and HTML to create screens.

Most of React revolves around "Components" - which are logical pieces of interface that can be swapped around your page, re-used, re-purposed and basically encapsulate everything your interface's "meat".

In our case, <App> is a component - and in actuality the main component of our app. This very similiar, conceptually, to creating custom HTML tags - each representing a set of interface parts grouped together to perform some logic. You will see <Button> and <TextField> components, <Slider> and <Navbar> components and - like here - more fully-featured, complete components like <App>.

<App> is coming from an import, and is actually defined in the App.js file. Let's take a look to see what this component actually looks like:

import React from 'react';
import logo from './logo.svg';
import './App.css';

function App() {
  return (
    <div className="App">
      <header className="App-header">
        <img src={logo} className="App-logo" alt="logo" />
        <p>
          Edit <code>src/App.js</code> and save to reload.
        </p>
        <a
          className="App-link"
          href="https://reactjs.org"
          target="_blank"
          rel="noopener noreferrer"
        >
          Learn React
        </a>
      </header>
    </div>
  );
}

export default App;

It seems to revolve around this App() function, right? That is no coincidence, and that is the first type of component I will talk about - a functional component. This might seem a bit weird at first - is this a component, or a function?

Well, as you'll soon see, every component in React is either a function or a class (more about that in the next article in the series). In and of itself, this should not matter to you. All you should understand is that each thing that you see on a page is a function, and understand how those functions compose together to create the UI.

Notice that the App() function is kind of simple - it just has a return clause, that returns a bunch of JSX (which, in this case, is mostly valid HTML). The only weird looking thing is this part:

<img src={logo} className="App-logo" alt="logo" />

What is this {logo} thing doing there? Well, that's the beauty of JSX for you - it's a javascript variable defined here:

import logo from './logo.svg';

Which gets the SVG logo from the file (streamlined by create-react-app) for you to use inside your component. This means that the React logo you saw on the initial screen, is actually imported right here in the component for display!

The rest of the JSX is just valid HTML. Whenever the App component is will be called, like in index.js as we saw before:

  <React.StrictMode>
    <App />
  </React.StrictMode>

React will make sure to place all the JSX returned by the element into is virtual DOM. In this case, App is a rather simple component - but we'll see in a second the power this approach brings us when the component are a bit more complex.

There is one small difference to note here - the class attribute of HTML tags needs to be swapped for className in JSX. This eventually get massaged into the class attribute you know and love, but it's important to mention the very obvious difference from plain HTML.

If you're following along with the video, I stop here to give an example of how to break apart a single component into multiple ones, talk about React Fragments and mess with the default project a bit to show you what's possible.

Props

Props. are values you can pass to a component, and then render different things based on them. For example, in the video I add a participantName prop to the MainInfo component I created. I can then pass to the component different attribute values in different parts of the app. This enables me, for example, to call that component once for a participant named "Tom" and once for a participant named "Not Tom". Both participants will get their own MainInfo component, with the name swapped out based on the value provided to the attribute.

Hooks

React hooks are... a bit tricky. I give an example in the video to a simple hook, but in retrospective I advise you to read the React Hooks intro and Hooks at a Glance for a better overview. They're short and concise, and give you all you need to understand about the syntax to get going, in my opinion.

Final words

This was a very short overview of functional components and the basics of React. Make sure to read the next article in the series to learn about class components, and - if you'd like a deeper dive - check out Dave Ceddia's Pure React book for a more thorough walk through React. This might look like an affiliate link, btw, but it's just a way for me and Dave to track how many visitors I'm sending his way (no money involved).

Shopify App From Scratch #7 - React Sidestep 1

Red Cap Tom — Fri, 29 May 2020 00:41:54 +0000

Deprecation Notice

Yeah, yeah, I know. I hate it too when people abandon tutorial series mid-way. But, due to (exciting!) circumstances, I'm calling it quits for now.

I'm thinking of just dropping a link to the full repo here - it's a mess, but it's something you guys can chew on instead of my empty promises.

If you'd like me to drop it here - let me know at hey@redcaptom.com.

Until we meet again - RCT :)

The Video (Scroll down for the article)

Coming soon!

Why React?

All right, so why should you even take the time to learn a new JS framework? If you're like me, you come from a PHP background, and grew up writing applications that consist of a php file that is generated dynamically from the server. If there's some form on the page, then when the user clicks it - the information gets send back to the sever, and the page gets rendered again (possibly with newer information). This used to be enough for a very, very long while.

It is no longer enough, though. When I'm looking at applications today, they're less like the web sites we had growing up, and more like our desktop applications, right? And the reaction I get when I tell people they should learn React is "I already know PHP, and maybe even some jQuery - why do I need React?".

The honest answer is that you really don't have to learn React. The kind of fuller answer is that if you want to match the experience that other web sites are providing for their users, you might want to consider adapting the same technologies that they are accustomed to dealing with.

As you probably already know, copy-pasting in the exact same way from other people's work is kinda problematic. What is perfectly OK is to draw inspiration from the feel other makers imbue their products with, and strive for the same aesthetic in your stuff.

Remember the end user of your application? All they probably care about is that your app feels comfortable, familiar and that it works. React, one of the main tools used in creating interactive web UIs today, can do just that for you. I think the average end users of the world would be very happy if most websites would feel and look the same from the functionality's perspective. That buttons and forms and sidebars act in the same way that they expect them to, instead of changing drastically from site to site. This lowers the technical barrier of entry into computers that a lot of people have.

So you should do it for the end-users. But really, you should also do it for you. The biggest benefit of React is composability and portability of components - write it once, use it everywhere. The encapsulation of code into components allows you to easily mix&match parts of your application to get the feel you want, and to re-use existing components from other people with the blink of an eye. This is insanely useful, and if you're writing without it you're missing out on a great ecosystem.

And honestly, it's just fun. I keep telling people that React changes the way that you think about development. I think more than any other technology that I've seen in the past, it really tries to get you to think declaratively first - on the way things will feel, instead of how easy it would be to build. This might not make much sense now, but bear with me - I will try to pass that sentiment on in the rest of the tutorial series, when we will actually build the app.

A note about these sidesteps

Note that my sidesteps do not intend to teach you things from scratch. They're intended to give you "hooks" (mind the React pun, please :) ) to allow you to read and understand different parts of the relevant technology. I urge you to go and actually learn these concepts yourselves if you're so inclined, but still attempt to give you a "fully-featured" tutorial right here and now.

React Itself - In The Next Video

I make a pretty good walkthrough of our makeshift app in the video, showing the different parts that can be made better using React. I think that the value itself will not become obvious to you until you start creating interfaces with it. After going over the initial learning curve, it's truly a remarkable piece of software to use. Follow the videos and the next two articles, and you'll begin to see the beauty:)

The next video will be a bit more hands-on than this introductory one - stay tuned!

Shopify App From Scratch #6 - Mockup Part 2

Red Cap Tom — Thu, 28 May 2020 23:05:28 +0000

Deprecation Notice

Yeah, yeah, I know. I hate it too when people abandon tutorial series mid-way. But, due to (exciting!) circumstances, I'm calling it quits for now.

I'm thinking of just dropping a link to the full repo here - it's a mess, but it's something you guys can chew on instead of my empty promises.

If you'd like me to drop it here - let me know at hey@redcaptom.com.

Until we meet again - RCT :)

The Video (Scroll down for the article)

Coming soon!

In Comes CSS

If you follow the Video above, you'll notice that I'm building up a new HTML wireframe, that has a bunch of improvements and some custom CSS to make it prettier. Here's the new, final result:

Here's the new HTML:

<html>
<head>
    <link rel="stylesheet" href="styles.css">
    <title>
        Countries We Ship Button
    </title>
</head>
<body>
    <div class="container">
        <div class="headerContainer">
            <div class="header">
                <h1>Countries We Ship To Button</h1>
            </div>
            <div class="prompt">
                <p>Please select the type of button you'd like to create:</p>
            </div>
        </div>
        <div class="singleButtonType1">
            <div class="type1Example">
                <button class="type1Button">Countries We Ship To Button</button>
            </div>
            <input type="checkbox" value="type1">Type 1
        </div>
        <div class="singleButtonType2">
            <div class="type2Example">
                <button class="type2Button">Countries We Ship To Button</button>
            </div>
            <input type="checkbox" value="type2">Type 2
        </div>
        <div class="toggle">
            <button class="toggleButton">Toggle</button>
        </div>
    </div>
</body>
</html>

And the new CSS:

/* A lot of the information can be learned from Shopify Polairs */
/* Form elements use the default of the OS  */

html {
    /* Load system fonts */
    font-family: -apple-system, BlinkMacSystemFont, San Francisco, Roboto, Segoe UI, Helvetica Neue, sans-serif;
    /* Make type rendering look crisper */
    -webkit-font-smoothing: antialiased;
    -moz-osx-font-smoothing: grayscale;
    /* Disable auto-enlargement of small text in Safari */
    text-size-adjust: 100%;
    /* Enable kerning and optional ligatures */
    text-rendering: optimizeLegibility;
}

/**
   * Form elements render using OS defaults,
   * so font-family inheritance must be specifically declared
   */

button,
input,
optgroup,
select,
textarea {
    font-family: inherit;
}

.container {
    display: grid;
    grid-template-columns: 200px 50px 50px 200px;
    grid-template-rows: auto;
    grid-template-areas: "header header header header" "type1 type1 type2 type2" ". toggle toggle .";
    row-gap: 20px;
}

.headerContainer {
    grid-area: header;
}

.singleButtonType1 {
    grid-area: type1;
}

.singleButtonType2 {
    grid-area: type2;
}

.toggle {
    grid-area: toggle;
}

.type1Button {
    /* So I can set a margin-bottom */
    display: inline-block;
    padding: 0.5em 1.5em;
    border-radius: 8px;
    border: 2px solid black;
    text-align: center;
    font-weight: bold;
    font-size: 1em;
    line-height: 1.65em;
    cursor: pointer;
    color: white;
    background-color: black;
    margin-right: 1rem;
    margin-bottom: 1rem;
}

.type2Button {
    /* So I can set a margin-bottom */
    display: inline-block;
    padding: 0.5em 1.5em;
    border-radius: 8px;
    border: 2px solid black;
    text-align: center;
    font-weight: bold;
    font-size: 1em;
    line-height: 1.65em;
    cursor: pointer;
    color: black;
    background-color: white;
    margin-right: 1rem;
    margin-bottom: 1rem;
}

/* 
.toggle {
    margin: auto;
} */

.toggleButton {
    padding: 15px;
    cursor: pointer;
    background-color: dimgray;
    border-radius: 5px;
    border-color: dimgray;
    border: 2px dimgray;
    font-size: large;
    color: black;
    font-weight: bold;
}

This is basically done! We now have a proper wireframe we can refer to when building our app. You can follow the video for my entire thinking pattern, but if you're just up for the final result - now you have it:)

Moving on - let's learn a little bit about React in our first (!) sidestep, before going head-first into building our application. If you've got React chops feel free to bypass the next 3 articles, and jump straight to article 10, which deals with Shopify's design system, Polaris.

Shopify App From Scratch #5 - Mockup Part 1

Red Cap Tom — Thu, 28 May 2020 22:26:33 +0000

Deprecation Notice

Yeah, yeah, I know. I hate it too when people abandon tutorial series mid-way. But, due to (exciting!) circumstances, I'm calling it quits for now.

I'm thinking of just dropping a link to the full repo here - it's a mess, but it's something you guys can chew on instead of my empty promises.

If you'd like me to drop it here - let me know at hey@redcaptom.com.

Until we meet again - RCT :)

The Video (Scroll down for the article)

Coming soon!

But I Don't Want To Draw Pictures, Tom...

All right, so we talked about getting set up with the tooling, the tech that we're going to use, how to get ideas, how to verify them and all the other nice things that come along with starting a Shopify app project. I think we're ready to dive into the coding, but before we actually write any lines of code, I think it's important to understand what we're going to build.

I, personally, never possessed the ability to actually jump right into the coding. I never could. I need to have some sort of visual aid to hold me responsible to the vision I wanted to build, or I make a mess of things. Really, really crappy spaghetti-unmaintainable-hellish-garbage code. The kind of code bad programmers - nay, bad people - write.

Solution? Mock it up! If I have a sketch of the screens in front of me in front-end projects (or a schema of the the flow in back-end projects) I tend to stay on track.

In the video I actually walk through the mental path of what I want to have on the page, and then build it piece by piece. Since I don't think the process translates well to the written medium (read: I'm lazy and doing this transcription after recording the video) I will just say a few words and show you the final product.

When thinking about a project, try to put yourself in the user's shoes. What buttons will they expect to see? Where on the page? What are they used to? What do they need to do? Remember that you are building a product for people who are intensely focused on creating more revenue and saving operations time. Is your app's value clear from the screens? Are they easy to understand, and easy to use?

Spend some time thinking before coding. It's surprisingly useful, and can save you literally hours in follow-up fixes. 100% would recommend.

Anyways, here's a view of the final sketch:

Wiring It Up

Having just a sketch is nice, but we will eventually need to output some sort of HTML to our users, right? JSX - the thing that we're going to actually output from our React app - is just HTML on steroids (which is actually a completely false statement from its implementation perspective, but we'll talk about that later).

Anyways, to come closer to the final codeneeded, I like to wire things out in plain HTML. This gives me the barebones feel of a page before having to actually do all the styling logic, and allows me to catch any possible interface bugs (for example, wanting to put too many buttons in a row, which looks fine in my sketch but bad in the HTML wireframe).

What I do, then, is create a preliminary sketch of how the HTML is going to look like, without any appended CSS. Here it is in all its glory:

And the final HTML:

<html>
    <head>
        <title>
            Countries We Ship Button
        </title>
    </head>
    <body>
        <div class="container">
            <div class="header">
                <h1>Countries We Ship To Button</h1>
            </div>
            <div class="prompt">
                <p>Please select the type of button you'd like to create:</p>
            </div>
            <div class="typeContainer">
                <div class="singleButtonType">
                    <div class="type1Example">
                    </div>
                    <input type="checkbox" value="type1">Type 1
                </div>
                <div class="singleButtonType">
                    <div class="type2Example">
                    </div>
                    <input type="checkbox" value="type2">Type 2
                </div>
            </div>
            <div class="toggleButton">
                <button>Toggle</button>
            </div>
        </div>
    </body>
</html>

And now we have a basic HTML wireframe of our application's main page.

In the next article, I'll deal with the CSS and making this resemble what the final, Polaris-based version will look like. In your own project, feel free to stop after this stage if you feel like you have enough inspiration to get coding!

Shopify App From Scratch #4 - Tech Stack

Red Cap Tom — Thu, 28 May 2020 20:45:34 +0000

Deprecation Notice

Yeah, yeah, I know. I hate it too when people abandon tutorial series mid-way. But, due to (exciting!) circumstances, I'm calling it quits for now.

I'm thinking of just dropping a link to the full repo here - it's a mess, but it's something you guys can chew on instead of my empty promises.

If you'd like me to drop it here - let me know at hey@redcaptom.com.

Until we meet again - RCT :)

The Video (Scroll down for the article)

Coming soon!

A Primer on the Origin of Shopify's Tech Stack

Shopify, since its early days and still in essence (it appears), is a Ruby shop. If you're not from the RoR (Ruby on Rails) community, or have not been around for a long enough time, that might not be very obvious - but there are 3 main tells:

Tobi Lutcke's (Shopify's CEO and the dude who wrote the original Shopify code) GitHub page is almost entirely Ruby:

He was actually a RoR core team member, and a lot of the Shopify stuff used to revolve around that ecosystem.

The official Shopify App tutorials come in two main flavors - JavaScript and Ruby.
It used to be that you could only deploy from the Shopify App CLI to Heroku - which is a big company today, but originated as a Ruby projects deployment tool. It seems that they have removed the option to deploy with the Shopify App CLI from the documentation since I wrote the article, however, which is a shame.

Why does this matter to you in 2020 (or maybe 2030? hopeful little me) reading this article? It goes to show that what we will be building in - JavaScript - only came into the game a bit later. This is indicative by some "rough edges" that remain in the development process for apps at the time of writing for the JS crowd. I do not think that the JS dev process is harder than the Ruby dev process, but it's important to say the above out loud for when you get discouraged. There's constant movement by Shopify in this space - things that are hard today might be made obsolete tomorrow! Keep on pushing. :)

Note: The aforementioned was added for the article and does not show up in the video. See? It's worth following the articles instead of the videos too!

The App We Will Be Building

Moving on - if you follow the video, you notice that I make a small tangent around here to talk about the app we will be building from scratch - Countries We Ship To Button. Take a look at the video from the beginning and up until 2:10 to get an idea of what the application looks like in practice.

I'm also namedropping quite a lot in the video, and doing so on purpose - the stack, when disassembled into its separate pieces, contains quite a few moving parts. But, in fact, what Shopify did was make a bunch of smart, sensible technological decisions for you. This might seem like a constraint on a first look, but it's really not - they're basically spilling the beans on what they use, and urge you to do the same.

The next is simply a list of all those technologies, some links, and where they fit in our stack.

React - The front-end framework

React is one of the three major front-end JavaScript libraries (along with Vue and Angular). It is considered the largest player in this space today, and for good reason - while a bit complicated to grasp at first, it steps up your front-end game quite a bit.

It takes a somewhat different approach to interface building than what you're probably used to from PHP or any server-rendered language: Instead of populating a of some source with information, it constructs the page piece-by-piece and reacts (get it?) to actions taken on the page to change the interface dynamically. That's weird if you're not used to it, but makes a lot of sense from the user's perspective - I click here, this loads in this part of the page, this is populated etc.

It's like jQuery on steroids and without $s all over the place.

We will be using it to create this beautiful interface:

I will make a few videos detailing this part of the stack in detail, which should at least give you the ability to read React code. If you don't have any React experience that's fine - you can fill the gaps as you go along - but I do recommend at least reading some information about it, like the official docs or Dave Ceddia's Pure React (this is not an affiliate link, just a way for me and Dave to see who's coming from where).

However, if you're already a JS person, spend very little time on catching up - I got you covered with some basics in the React sidestep. Stay tuned.

Next.js - The React Framework

React, in and of itself, is lacking some basic utilities that can help you write code that is more performant (and, actually, help speed up the coding process itself). For this purpose, Vercel (formerly Zeit) came up with Next.js - the de-facto standard React framework.

If you're not really into React it's kind of hard to understand how Next stacks up next to it, and what does it even offer. In our application, the main place you will encounter Next is in the custom server it creates at the start of server.js. We will not really be using it all that much in our code, just reaping the general benefits it produces on the side. I will elaborate more about that in the Next.js sidestep in this tutorial.

Polaris - The Shopify Design System

Keep in mind that you will be building inside the Shopify admin, meaning that your app should mimic the look and feel of the Shopify admin as much as possible. Knowing that this is not an easy fit, the Shopify people released Polaris - a design system that's intended to allow developers to get Shopify look and feel with little to no effort.

Design systems, in most cases, are carefully-calculated interface languages, that are tuned to get a feel across a screen. You can read about it some more here, but for now it's enough to say that Shopify provides React components that we can use in our apps. They have the same color, animations and general feel as the Shopify admin's interface, which makes it relatively easy to create - inside your embedded apps - a familiar feeling for your merchants. I have a full side-step on this as well - stay tuned!

Node.js - JavaScript, Everywhere!

Up until now, we talked about the front-end part of things - but there's a lot going on in the back-end as well! While we will code the front-end of the application first, the back-end is the real heavy lifter, and it's written entirely in Node.js.

Saying that you write node code is a bit terminologically incorrect - it's like saying you're writing CLR instead of saying you're writing C# (which is not a great analogy, but the only one I could think of that is well-known enough to make sense). Node is a runtime - it is a way of running JavaScript on the server. What you're actually writing is JavaScript - much like you do on the front-end - except you do it on the backend, with the help of various tools and libraries that are designed for backend apps (like filesystem access, for example).

The interesting bit about Node.js is that it's basically built around providing code as a service. What I mean by that is that it was originally built heavily around the concept of requests and responses, and propping up servers - see this example - as a main "course of action". This is a bit different than other backend programming languages that are more "general" in nature, and do not basically require you to prop up some server somewhere in your application.

This is not true universally today, and Node is used everywhere in many different configurations, but for our purposes it's best to consider it as an API writing language. We will be building a set of endpoints to be used by our front-end application, and those endpoints will perform various tasks that receive, modify and fetch information across our application and the Shopify servers. More about that in a future sidestep, though - for now, treat Node as JS on the server.

Koa - A Node.js Web Framework

While you can totally write your servers in pure Node (and many do), it actually makes much more sense to use a proper web frameworks to run production-grade code. Those type of frameworks provide lots of utilities for you to perform common activities without having to re-write code from scratch - stuff like looking at the body of HTTP requests, handle specific types of HTTP headers, etc.

Shopify recommends the use of Koa, which is a slimmer, more modern alternative to the "standard" Node.js web framework - Experss. The beauty about Koa is that it comes "without batteries" - meaning that you only get the base functionality out of the box, and then need to append more and more layers as you see fit. This makes your code a bit more understandable (but also a bit longer), since all the components of the framework are explicitly mentioned in your server.js file.

GraphQL - Query Language For Rest APIs

GraphQL is a rather new, very cool runtime (and associated query language and conceptualization) that seems like a really weird idea at first glance. What it's basically saying is - let's make a new query language, that's not really like SQL (so is a bit harder to learn), and use that to query our APIs.

A keen observer will note that most APIs wrap database / ORM calls anyways, right? An API is just a fancy way to prevent your users from performing SQL queries on your database themselves, isn't it? Why do we need all of this fancy, shiny new stuff?

Well, letting your users run raw SQL queries on your database is a very bad idea. Let's get that out of the way first. Do. Not. Do it.

Having said that, have a way to query, rather than just call, your APIs is kinda awesome. Imagine you have a need to get some data in your application, that requires information from two different API endpoints. Usually this means two API calls - one for the first resource, and another one for the second resource. Then, you'd have to parse the information from both of those endpoints and return that data to the main application.

With GraphQL, you can instead perform a single query, that gets you the information that both API endpoints provide in a single API call (to the GraphQL query root). In this query, you can also query only the relevant data you need - mostly removing the need to do data massaging later in the process!

We will not be using GraphQL in our specific application , but I will be making a sidestep for it anyways since it's really important.

Apollo - GraphQL Client

The foremost implementation of GraphQL for JavaScript is Apollo, which is simply a GraphQL client you can use from inside React. I will talk more about it later. For now - just think of it as a component you can drop into your app, and perform queries with.

Shopify Liquid

While used very sparsely in this app (it's glory moment is integrating the button into the merchant's store, and that's about it), Liquid is the way one write Shopify sites. I will not be doing a full sidestep on it, because it's really out of scope for this series (that is already looking like it's going to be super long anyways).

That about sums it up for the tool stack. Let's start planning our app!

Shopify App From Scratch #3 - Tools

Red Cap Tom — Mon, 25 May 2020 22:17:09 +0000

Deprecation Notice

Yeah, yeah, I know. I hate it too when people abandon tutorial series mid-way. But, due to (exciting!) circumstances, I'm calling it quits for now.

I'm thinking of just dropping a link to the full repo here - it's a mess, but it's something you guys can chew on instead of my empty promises.

If you'd like me to drop it here - let me know at hey@redcaptom.com.

Until we meet again - RCT :)

The Video (Scroll down for the article)

Coming soon!

Introduction

Tooling is a touchy subject for programmers - each and every one of us has his own permutation of programs, scripts, config files, keyboard shortcuts and whatnot that we use on a daily basis, and which we trust to the core. Even more specifically, each language has its own ecosystem of tools and best practices - and developers who are part of some ecosystem tend to gather around the same tooling.

While I do not subscribe to the dogma of "this tool is best since ever", I do strongly feel that if a tool is generally acceptable in the community you work in, you should at least consider using it. If possible, consult with a long-time developer in the same ecosystem and get his views on wha'ts good and what's not. They've most likely been at the same junction that you are now at an earlier time, and have insights you could use.

This also has the added benefit of exposing you to new paths of thinking that might've not been obvious before. An easy example is ngrok - a tool I will talk about soon. Unless you have experience port-forwarding to expose your local machine to the outside world, you might not fully appreciate this tool. But, I can assure you, it's a pretty awesome piece of software that deals with a tricky bit of networking that is not obvious from first sight. It also sent me down a rabbithole of networking that I'm glad I went down, since it made me a much better dev afterwards. This shows another benefit of learning new tools - the exploration of new thought directions the tools throw you in, that benefit you professionally.

I will caveat the preceding notion, however, by mentioning that tooling is just that - tooling. Don't let it overwhelm you or detract you from the nail in front of you - the problem might become easier to deal with using a great tool, but it will not solve itself. Lower your head over they keyboard and resume coding, please. :)

Anyways, back to business.

Code Editor - VSCode

I'm a big fan of Visual Studio Code for anything web-dev. I was a Sublime Text user for many years, and eventually got to work at a company that used VSCode and fell in love with it. If you're deep in the JavaScript ecosystem (and you soon will be, as Shopify apps are pretty much a full-stack JS endeavor), this editor is just feature-packed: Formatters, linters, syntax higlighters, smart snippets, auto-refactorings, test framework bindings and what have you.

The way I set it up usually is one workspace per "mental zone" - one for writing these tutorials, one for client applications, one for testing and learning, etc. Since it's pane-based, you also have a great separation of concerns and can edit server-side and front-end code side-by-side. You will see in the next videos that I try to first build the front-end component, and then iterate on back-end parts from that front-facing component (and dual-pane editors are a great asset in that approach).

Terminal Multiplexer - `tmux`

You don't really need tmux. Nobody really needs it if they're mostly working in the editor (as you guys will). But, whenever you do find yourself in need of a terminal, there's nothing quite like it. It lets you construct a set of multiple terminal windows in the same operating system window, arrange them however you see fit and switch between them with a key binding (as well as naming them, have more than one set of windows in the same window and much, much more).

In our flow, we will use 3-4 windows at any given time: One for ngrok, one for our dev server running with npm run dev (more about this later), one with the project's folder open to do git add . && git commit -m"some commit message" && git push -u origin master (again, more on this later) and (optinally) one with a test project to run test commands in. tmux is perfect for this - you can see all incoming requests in the ngrok window, any error messages in the server dev window, commit and push after every fix in the project/git window and run sample commands in the optional test window.

This is of course perfectly feasible with a regular terminal window (or a combination of a terminal window and the in-editor terminal), but to me the tmux approach is much cleaner and fits on a single monitor to my left (and not my main monitor in front of me that I use my editor on).

Note, however, that tmux is strictly a Linux tool at the time of writing this article. If you're on a Mac - use iTerm2. On Windows - ConEmu is a great choice.

Don't get hung up on terminal multiplexers too much for now, though - you already have enough tools to ramp up on, leave this one for the very last (if at all).

Node version management - `nvm`

NodeJS is at the core of most of what we will be building here. Your build tools run on it, you will be writing code in it and use its default package manager npm extensively. There is an inherent problem with Node, though - its developers tend to create breaking changes between versions.

This is not a problem per se - Node's developers chose to prioritize adding new features as the language progressed instead of maintaining backwards compatibility - i.e. making sure old code works with new versions. It becomes a problem once you rely (as we will) on multiple packages, created by different authors at different times using diffferent versions of node.

For the most part, let npm do its thing and set you up with the correct packages for your node version and whatever it is you're currently working on. But - what happens when you revisit an old project in a year from now, or want to use code from an older project written by someone else?

You'd need to have installed - on your machine - different versions of Node. Again, this in and of itself is not complicated - just download each version to a different folder, add the binary to the path and be done with it, right?

Wrong. It's a shitshow. You'll think you are using version A, when instead you'll be using version B and then committing code to your repositories that is designed to use with version C. Let's just... not.

Instead, you can use nvm for Mac / Linux (or nvm-windows for Windows). These are tools that download, switch and manage Node versions for you. You could easially install some version of node, then switch to it using nvm use 12.16.3 when you want to use Node 12.16.3.

This way you don't actually have to deal with configuring different Node installations - the manager does it all for you. While this value might still not be clear to you, wait until you have to work with other people's older code. Fun to be had by all! :)

Sidenote: This sounds scary, when I'm thinking about it a bit deeper. It's really not, though - this is a solved problem. Use the tools at hand, get used to them, and move on. Lots to do, lots to do!

Tunnels, oh tunnels - `ngrok`

A Shopify embedded app (like the one we are going to soon build) does not actually run on the Shopify servers. As such, it requires some place to be hosted in. We'll talk about deployments way, way later, but for now we'd like to have someplace to run our apps from, so they can be embedded in Shopify.

Traditionally, you'd need to throw your code up on a server for that to happen, or use tricky network hacks to get your local computer to act as a world-facing server. This whole endeavor is not really fun for anyone when all you want is a URL that leads to your computer, and to the directory that you run your code in. Well, that's what ngrok is for.

I could into the details of how ngrok works, and dive into what tunnels are, what the hell introspection is and why should you care, but the honest (and lazy) answer is that it's out of scope for this article. If you'd like a follow up on that, hit me up here or on Twitter and I'll write up a longer post.

For now, just know that whenever you'll run your code in one terminal window, you can also expose it to the world by running ngrok in another terminal window. This will allow us to "mimic" a hosted app on our machine, and have that code run inside the Shopify Admin panel. More about this - later.

Shopify official stuff

I go deeper into this in the video, but there's also a few pieces of tooling Shopify itself provides. I suggest you watch the video for the visual walkthrough I do there for the following items, but if you still want a readable version - here's a short one:

Shopify App CLI - This is a Shopify project that is intended to be used as a supplement tool for developing apps. It scaffolds, serves, deploys and generally holds your hand when building Shopify apps. I would say that you should wait before using it. Instead, first learn on how an app is built, what is holds in it, where are all the important bits and pieces go - and then use the CLI to scaffold your projects.
Shopify Partner Account - All Shopify app builders are considered Shopify Partners, and are entitled to some nice perks and a direct support line to Shopify, to solve any issues. After you sign up for the (free) account, you will get access to a nice dashboard to manage all your apps and stores. We will use it extensively in this tutorial, so stay tuned.
Shopify Development Store - A Shopify Online Store costs 29 USD a month. Since we will be developing for Shopify, the platform offers us a way to skip that fee and have a live store at our disposal for testing purposes. We will use one of those extensively as well for testing our app with.

A note about operating systems

I am a Linux user. I have no bad things to say about Windows. I have no bad things to say about Mac OS. I have no bad things to say about BSD. I don't care what you use, as long as it fits you and works for you. Don't let anybody ever tell you that you would become a better dev by abandoning Windows for a unix-based operating system. It's bullshit. Some of the best devs I know are Microsoft hounds, slinging C# and .Net in a scale you would not believe. Dogma is for the weak - write code, be better, and discard all the noise.

Having said that, feel free tot talk to me about help in setting up stuff for your own operating system for the sake of this tutorial. If I can't solve it myself, I can most likely refer you to the correct resource. And if your problem is interesting, it might merit another DEV post! :)

Shopify App From Scratch #2 - Idea Generation

Red Cap Tom — Sun, 24 May 2020 20:24:26 +0000

Deprecation Notice

Yeah, yeah, I know. I hate it too when people abandon tutorial series mid-way. But, due to (exciting!) circumstances, I'm calling it quits for now.

I'm thinking of just dropping a link to the full repo here - it's a mess, but it's something you guys can chew on instead of my empty promises.

If you'd like me to drop it here - let me know at hey@redcaptom.com.

Until we meet again - RCT :)

The Video (Scroll down for the article)

Coming soon!

Introduction

Before we dive into the technical parts of how to create an application, I wanted to walk you through the process I use when trying to generate Shopify app ideas. I knew Shopify was one of the bigger platforms out there, and that many people were building various external integrations for it - so the very first thing I did was heading over the to the Shopify App Store to get some inspiration.

The Shopify App Store

A good first thing to look out for is the Staff Picks section - this will give you a quick peek into what's trending and can help you figure out what people are building (and how well are they doing, and how much money they are charging). While browsing the store, you'll notice there are a bunch of categories on the top left menu. If you're verifying your idea, and not looking for a new one, try to figure out where you will fit inside one of these categories. Remember that it's much easier to fill a hole in an existing category then to go out on your own and create a new category from scratch. It will also serve as competitor research - you'll see who's who in your niche and can gauge how hard it will be to carve your place on the podium.

If you're generating an idea, like me, start clicking through stuff and see what is actually being built. Something you see happening often is a developer taking an external API and offering a "wrapper" in the form of an App. An example (not shown in the video) is this app, which is basically what you'd expect from a Google Shopping / Ads client for Shopify - it wraps the correct API calls in a familiar Shopify App interface for the merchants, and offers some added functionality. That's an awesome approach that I really like, and if you have some cool API that you know about you should definitely consider then you're saying maybe Shopify merchants will be it will be useful. So if I merchants think about crafting or, you know, wrapping that API in some Shopify app and adding that other Shopify as there wasn't an extension.

Alright, so you're inspired. Let's now go see what people are actually struggling with - maybe you can help them out?

Facebook

To be honest, the store itself did not prove super useful for me - I did not want to copy an app by someone else, I wanted to create something out of a real need in the community. For that, I went into a bit of a Facebook Groups binge and ended up browsing extensively through this group. There are a bunch of different groups on slightly different topics, but I would start with the dropshipping or newbies one (there are literally dozens of them) and start really listening to what people are talking about.

My immediate goal was to find people who difficulties that no app was meeting at the moment. If you look at these types of groups, every some time a person would come up with a genuine question about a topic that apps are not addressing. Sometime it's an external integration, sometime it's a visual item they'd like added to the store, sometime it's just an annoying Shopify glitch they need to get over - in all of those cases you can come in for the win and scoop an awesome app idea.

The nice thing about this platform is that it's akin to inserting yourself into the mind of the merchant, and trying to figure out what stings them. What they're struggling with on the daily, what they feel should be more accessible, or easier, or faster.

Haven't found anything interesting here? We always have Reddit...

One way the Shopify subreddit (note that I've filtered by flair to get only app dev related threads) differs than the facebook groups mentioned above is that the discussions seem to be a bit more fruitful. It might have something to do with the fact that most people are practically anonymous, but the subreddit is much less spammy than the FB groups and has substantially better content, in my book.

This is a great place to not only get ideas for new apps, but also to find co-conspirators for your app journey, beta testers, API help and whatever else you need that has to do with the Shopify ecosystem. It's truly a treasure trove of information and I try to use it on the daily.

Having said that, I was always a forum kinda guy - I grew up on messaging boards with fancy HTML signatures and 57-page threads. As it turns out, Shopify has community forums as well.

Shopify Community

Shopify Community has a bunch of different forums you can browse to get a whiff of all the different merchants experience on the daily, and unlike Facebook and Reddit it is very, very well organized. Specifically, the Shopify Apps Forum proved to be very useful for me.

The posts on this forum split in the middle to "what is the best app for X" posts and "I built app Y" posts. This is not very useful, but here and then you find diamonds in the rough that make it worth it - in my case it was this thread announcing a new app for blog comments. The guy who built it posted the thread and disappeared somewhere around 2014. So what is this whole blog comments thing anyways?

Say you have a blog on Shopify. It makes sense that you would like to be notified when a new comments is left on one of your posts. It turns out Shopify does not offer blog comment notification at all - there is no way to trigger an e-mail when you receive a new comment from the Shopify admin panel. I saw this and a light went on in my mind - that's exactly what no-code tools are built for: listening for something happening (a blog comment coming in) and triggering a series of events (in our case - an e-mail message).

So I sat down and wrote a no-code tutorial on how to get blog comment notifications via e-mail (see my comments in the e-mail for the conversation, but the full version of the tutorial is available here). Now, despite this not being an app, I'm still getting a bunch of comments and e-mails following this thread, that enable me to connect with merchants in a better way than ever before. It's pretty awesome that I get to have that connection with merchants, since they often tell me in person what are their troubles and needs, which leads to more apps or tutorials, which leads to more merchants... you get my point.

You should spend your time helping people. Be of service. If you take a single key point away from this whole series is this point - be useful to the merchants. They need you to show them the nooks and crannies of the platform, and they are willing to put good money for good apps and resources. Just solve an actual need, and you'll be surprised how fast conversations will start with merchants.

Just generate conversations, try to become part of the community and be helpful before you start something. Don't be that guy that posts links to their stuff but doesn't provide any value whatsoever.

What will we be building, then?

Took me a while until I found something that was interesting - but after a daily routine of visiting the forums, answering things helpfully and looking around I finally settled on building an app based on this thread. It's a simple concept - a button, placed somewhere on your site, that mentions which countries you ship to and which you don't. That should prevent people from ordering products from the store if the store does not ship to their country, preventing undesired orders from coming in.

This looks kind of simple, right? It's a button, that gets some information about the shipping areas of the store, and shows up nicely with a pop-up message. It turns out, though, that just getting this up and running is a bit of a challenge if you don't know all the players involved. There's quite a bit going on in the back - getting the app reviewed, authentication to the store, API calls that fail weirdly, responsiveness across various stores... a lot of moving parts.

So I started small - built a working version in HTML, CSS & JS. Then started working on the React/Polaris interface. Then wrote the backend API routes, and called them from the front-end, and added a bunch of niceties along the way to make it nicer for me to maintain. And from there I just iterated until I figured out how the app should look like, after talking to people and listening to what they needed and wanted.

And if you take anything out of the tutorial series, let it be this - conversations with people, helping them for nothing in return, being of service and being of use is the best thing you can do for yourself. Be very responsive. Talk to people as much as possible. Be very forthcoming and honest. Dive in - I think when you look at it like this, it makes everything much more fun. :)

Shopify App From Scratch #1 - Introduction

Red Cap Tom — Sun, 24 May 2020 20:22:03 +0000

Deprecation Notice

Yeah, yeah, I know. I hate it too when people abandon tutorial series mid-way. But, due to (exciting!) circumstances, I'm calling it quits for now.

I'm thinking of just dropping a link to the full repo here - it's a mess, but it's something you guys can chew on instead of my empty promises.

If you'd like me to drop it here - let me know at hey@redcaptom.com.

Until we meet again - RCT :)

The Video (Scroll down for the article)

Coming soon!

What now?

So, in December of 2019 I set out to build a Shopify app.

Shopify is an e-commerce platform that is, by far, the largest and most advanced one in the market. While I'm totally a fanboy, I can actually back that up by looking around - everyone and their brother is opening up a Shopify store. They offer solutions for payments, for shipping, for store design and whatever else you might be interested in as a business owner in need of an online presence.

The Shopify App Store

At some point, Shopify figured out that they need an App Store - a central location to allow third party developers to create merchant-tailored experiences in various niches. Shopify will provide developers with the tooling, the documentation and an 80% cut of every app installation - and the developers will come.

And come they did - 3,200 apps later, it looks like a win for Shopify. And to be frank, I see why from a developer's perspective - you get the means to build a money-making thing, with first-class support to boot. Not a a bad deal.

The Shopify App development experience

However, even if you've got some notches in your developer belt, you might hit some bumps along the road. If, for example, you come from only frontend or only backend work you might find yourself struggling through their tutorials. Heck, I've hit my fair share just trying to make sense of the architecture decisions they made, so I can follow best practices of each platform as I'm building my app.

So, having went through the experience myself, I can tell you that there are plenty of resources for learning the technologies involved and a (somewhat) active ecosystem around Shopify Apps. The problem begins when you're trying to connect all the parts together - to me, the official tutorial is a bit lacking in basic concept explanations. I know, I know, it's out of scope for Shopify to explain "external" things - like what a custom Next.js server is, or how is Koa different from Express and why they chose to use it over Express, or how to deploy your app to Heroku in a way that keeps you sane and asleep at night, or... you get the picture.

Wait, that sounds like an awesome opportunity to make a mark in the tutorial space, isn't it? Well, this is the reasoning behind what you're reading right now. I want to make this the resource I wished I had when I started working on my app.

This tutorial series

In practice, what I'm trying to achieve in this tutorial series is a full walkthrough of what it's like to develop a Shopify App - the thought process, the tools and the nitty-gritty details that no one is talking about in the official resources. I will walk you through from setting up your machine for work, getting an app idea (or verifying an existing one) all the way to deploying your app and (most likely) the marketing aspects you have in front of you.

You'll see that I prefer to dwell on some things and skip others. Generally speaking, I will elaborate on non-Shopify things in what I call sidesteps, which are mini-deep-dives for the uninitiated. I will do those for React, for Koa, for Next.js and other goodies you need to know just enough of to get along.

This will make for a rather long tutorial series - I assume it will be around 60-70 videos when I'm done (ambitious me!), each one between 5-45 minutes, depending on the subject. Wherever possible I'd make an attempt to stick to 10-ish minute videos, because I too cannot stand never-ending series, but bare with me if I'm going over budget here and there.

About going off the path

I'm posting this series because I wanted to have one like, it and couldn't find one. I might at some point decide that I'd like to take it in some direction that tangents from the original path.

If you're following my work and would like me to take some time to explain something that I haven't covered - just ping me at hey@redcaptom.com. I'll find the time and make a video, if possible, and I assume that if you're struggling with this you're note alone.

Now, let's do this!

Forem: Red Cap Tom

Shopify App From Scratch #12 - User Interface 2

Deprecation Notice

The Video (Scroll down for the article)

More User Interface

A Note on Redux

An Offer

Shopify App From Scratch #11 - User Interface 1

Deprecation Notice

The Video (Scroll down for the article)

Building the User Interface

Getting ready

a Note About the Terminal

Starting For Real Now

Shopify App From Scratch #10 - Shopify Polaris

Deprecation Notice

The Video (Scroll down for the article)

Introduction

What's in a design system?

Why should you care?

Shopify Polaris - Shopify's Own Design System

Example Component - Button

Example Component - Callout Card

Shopify App From Scratch #9 - React Sidestep 3

Deprecation Notice

The Video (Scroll down for the article)

React class components

Introduction

Class Components Are Heavyweights

A note about classes in JavaScript

How Does One Identify A React Class Component In The Wild?

The General Structure

The Breakdown

The React Component Lifecycle

Final words

Shopify App From Scratch #8 - React Sidestep 2

Deprecation Notice

The Video (Scroll down for the article)

A Short Primer

Setting up

Scaffolding the project

In Comes React

Funcational Components

Props

Hooks

Final words

Shopify App From Scratch #7 - React Sidestep 1

Deprecation Notice

The Video (Scroll down for the article)

Why React?

A note about these sidesteps

React Itself - In The Next Video

Shopify App From Scratch #6 - Mockup Part 2

Deprecation Notice

The Video (Scroll down for the article)

In Comes CSS

Shopify App From Scratch #5 - Mockup Part 1

Deprecation Notice

The Video (Scroll down for the article)

But I Don't Want To Draw Pictures, Tom...

Wiring It Up

Shopify App From Scratch #4 - Tech Stack

Deprecation Notice

The Video (Scroll down for the article)

A Primer on the Origin of Shopify's Tech Stack

The App We Will Be Building

React - The front-end framework

Next.js - The React Framework

Polaris - The Shopify Design System

Node.js - JavaScript, Everywhere!

Koa - A Node.js Web Framework

GraphQL - Query Language For Rest APIs

Apollo - GraphQL Client

Shopify Liquid

Shopify App From Scratch #3 - Tools

Deprecation Notice

The Video (Scroll down for the article)

Introduction

Code Editor - VSCode

Terminal Multiplexer - tmux

Terminal Multiplexer - `tmux`

Node version management - `nvm`

Tunnels, oh tunnels - `ngrok`