DEV Community: Billy Jacoby

How to use tRPC types outside of a monorepo

Billy Jacoby — Thu, 30 May 2024 13:23:00 +0000

Introduction

If you've stumbled upon this post, then I'm sure you're at least sort of familiar with what tRPC is and some of the benefits that it can offer. But for those who might not be here's the tl:dr;

tRPC is a modern and lightweight framework for building typesafe API clients in TypeScript. It helps to simplify API communication and greatly enhances type safety. It's common for multiple projects or services to rely on a shared API structure or models.

Most people will use tRPC in a monorepo structure, and while this is definitely the easiest approach this isn't always possible. In my specific instance I've worked on a number of React Native projects that just don't do well in a monorepo. I tried to find simple solutions or guides for how to share types from a tRPC repo into my React Native repo but ended up having to do all the footwork myself.

I'll share what that all entailed and how to go about exporting our types as a NPM (or Github) package for consumption from anywhere.

Setting up the tRPC Repository

A typical TRPC repository follows a structured organization, separating API routes, controllers, and schema definitions. Types play a crucial role in tRPC repositories, ensuring proper handling of data payloads and guaranteeing type safety throughout the codebase. For this example we'll create a dead simple tRPC project to use as our guide. We'll start with the Separate Backend and Frontend example from the tRPC website.

If for your specific use case you don't want to publish a package to share types, then these repos are a great example of how to acomplish this. The remainder of this post will focus on adjusting the backend repo in from this example to publish a types package to your registry of choice, and adding and consuming these types.

I've created a fork of this repo to ensure that it doesn't get lost or taken down after this post is published. I've switched the package manager to yarn instead of npm and also upgraded all of the dependencies as of posting.

If you'd just like to view the finished version with publishing scripts included that can be found here.

We'll start off by cloning this repo and installing the necessary dependencies.

git clone https://github.com/billyjacoby/backend-trpc-api-boilerplate.git
cd backend-trpc-api-boilerplate
yarn install

After we've got this pulled we should be able to run and view out basica tRPC server that lists Users and Batches by visiting http://localhost:4000. This should look something like this:

Visiting the links on this page should just return a JSON document containing the relevant objects.

Setting up the package scripting

Now that we've got a basic server up and running we can start work on exporting the types as a package.

After running yarn trpc-api-export in the root of the project you'll see that we have our types exported in our trpc-api-export/dist folder. This is a great start! We'll want to add a new package.json file to this directory that includes any packages that we'll need in our client application. This is also how we'll name our types package so run through the npm init command in this directory and fill it out accordingly. In this example, the imports that you see in this directory's index.d.ts file. For this example we'll need the following packages:

    "@trpc/server": "^10.43.3",
    "express": "^4.18.2",
    "express-serve-static-core": "^0.1.1",
    "qs": "^6.11.2",
    "superjson": "^2.2.1"

Though these can be installed using the yarn add ... command in the trpc-api-export directory, we don't actually need the packages installed again here. We just need to ensure that the client has them installed when they are using this package.

Next in order to make this as easy as possible we want to add a bash script that will cd into the export directory and publish our package for us. I've noticed weirdness before when trying to do this without explicitly creating a workspace, so this is the best solution for me.

Add a bin/publish.sh file that contains the following:

#!/bin/bash

cd trpc-api-export && yarn publish
echo "Published!"

Then make sure that you've got a publish script added to the trpc-api-export/package.json like this:

...
  "scripts": {
    "publish": "npm publish --access public"
  },
...

Publishing the package

Once all of these steps are complete we should be ready to publish the types package. If you plan on publishing to NPM ensure that you've got your account setup as necessary here. To start we'll be publishing a public NPM package here.

Once you're all ready to go with NPM, lets edit our top level publish script to make sure that we're bundling the types before publishing.

Our top level publish command should look something like this:

...
  "scripts": {
    "trpc-api-export": "tsup --config trpc-api-export/builder/tsup.config.ts && npm run format-fix",
    "publish": "yarn trpc-api-export && ./bin/publish.sh",
    ...
  }
...

Now when we run the yarn publish command at the project root, we'll be bundling and publishing our package to NPM!

Importing and using the package

Importing types should be pretty straightforward. The one thing to remember is to add your package as a dev dependency to ensure that the dependencies of the types package are not added to your final build outputs.

yarn add -D @billyjacoby/trpc-example-package

And voila! After this, you can access all the exported types from your tRPC router in any other repo. In most cases importing the AppRouter and using that in conjunction with inferRouterOutputs & inferRouterInputs should get you every type that you could need.

As I mentioned this has come in super handy for me on a number of React Native projects. There are also a few other options for publishing these packages more privately. I usually publish private packages using Github's registry which makes it super easy to share the package with any repositories that belong to the same organization.

Versioning and Maintenance

Versioning the exported types package is essential to ensure compatibility and backward compatibility when consuming repositories receive updates. Follow established versioning best practices, such as Semantic Versioning (SemVer), to communicate breaking changes or feature additions effectively.

I've written a number of scripts that largely manage this aspect for me, and plan on publishing a follow up that includes a few of these.

By far the most beneficial thing to add to all of this is automatic package publishing via CI. This can also be configured to publish to specific tags based on certain criteria.

Conclusion

Exporting and sharing types between repositories in tRPC projects offers significant benefits, such as improved collaboration, consistent data contracts, and enhanced type safety. Adopting this approach fosters reusable and maintainable codebases across different projects or services, facilitating seamless integration

If you're starting from scratch then I certainly recommend a monorepo approach wherever possible. But if you're like me then this isn't always the case. This has been the lowest friction way to share these types in my experience.

Leave a comment below with any questions, or if you'd be interested in a post detailing the automation of this process using Github or Gitlab actions. Thanks for reading!

Building a GatsbyJS Theme - Part Three

Billy Jacoby — Thu, 21 Nov 2019 15:39:17 +0000

Making our existing theme composable

This is part three in a multi-part tutorial series on building your own Gatsby theme from scratch.

Please checkout the Introduction, Part One, and Part Two of this series if you haven't yet, as we will be picking up right where we left off at the end of part Two.

The finished code for this portion of the tutorial can be found on my github repo here.

The end goal of this tutorial is to break down some common website functions into their own respective themes in order to allow us to use them as basically their own components. That means that we need to make sure that each component plays nicely with each other. We'll have to change a few things in our theme to do this.

Here's what we'll be tackling in this part of the tutorial:

Change existing theme name
Update our project's dependencies
Add the ability to take options into our theme
Pass options in to our theme
Export components from our theme to be used in our site

Change existing theme name

The theme we have been working on this far we have named gatsby-theme-tutorial. the first thing that we'll do here is change this name to reflect the goal of this theme. We'll change this directory name to gatsby-theme-style for now. After doing this our folder structure will look like this:

gatsby-theme-tutorial-development/
--packages/
  |--gatsby-theme-style/
    |--package.json
    ...
--site/
  |--package.json
--package.json

We'll also need to update our packages/gatsby-theme-style/package.json and site/package.json file to change the name of our theme from gatsby-theme-tutorial to gatsby-theme-style.

We're also going to move the index.js file from our theme's pages folder into our site's pages folder.

Before we can continue with this build and run our development site again, we have to do a few other things.

Update our dependencies

Next, we will need to update out gatsby-config.js in our site directory, but before we do this lets go ahead and update all of our packages by running yarn upgrade in our root project directory.

We're doing this mainly because it's been a while since we've done any work on this tutorial and we want to be sure we're using the most up to date packages.

After everything has been updated, lets import our theme as a plugin rather than using the __experimental tag that we've been using.

site/gatsby-config.js

module.exports = {
  siteMetadata: {
    title: `New Gatsby Site`,
    description: `A website using our Gatsby theme!`
  },
  plugins: [
    {
      resolve: "gatsby-theme-style",
      options: {
        // blank for now, but we;ll be coming back to this
      }
    }
  ]
};

Now if we run yarn workspace site develop you should see that our site works the exact same way that it did at the end of our last tutorial. Now about that empty options object...

Passing options into our theme

We can pass any number of options to our theme using the options object from the gatsby-config.js of our site. This can be anything from color schemes, to navigation items, and much more. We're going to start by passing an option that tells our theme if we would like our Layout component to continue to wrap the root element - what it's currently doing.

site/gatsby-config.js

module.exports = {
  siteMetadata: {
    title: `New Gatsby Site`,
    description: `A website using our Gatsby theme!`
  },
  plugins: [
    {
      resolve: "gatsby-theme-style",
      options: {
        wrapRootElement: false
      }
    }
  ]
};

Now in order to be able to access this options object in our theme we must make a change to our theme's gatbsy-config.js

packages/gatsby-theme-style/gatsby-config.js

module.exports = themeOptions => ({
  siteMetadata: {
    title: `Gatsby Theme Tutorial`,
    description: `A tutorial for building a GatsbyJS theme from scratch!`
  },
  plugins: [
    {
      resolve: `gatsby-plugin-page-creator`,
      options: {
        path: `${__dirname}/src/pages`
      }
    }
  ]
});

This will enable us to access the themeOptions object just about anywhere in our theme to make decisions based on the options passed in. Now lets utilize this object in both our packages/gatsby-theme-style/gatsby-browser.js and packages/gatsby-theme-style/gatsby-ssr.js files to determine whether or not we should wrap our root element in our theme's styles or not.

packages/gatsby-theme-style/gatsby-browser.js

AND

packages/gatsby-theme-style/gatsby-ssr.js

import React from "react";
import Layout from "./src/components/layout";

export const wrapPageElement = ({ element, props }, themeOptions) => {
  // props provide same data to Layout as Page element will get
  // including location, data, etc - you don't need to pass it
  if (themeOptions.wrapRootElement) {
    return <Layout {...props}>{element}</Layout>;
  } else {
    return;
  }
};

After we make this change we see that our website no longer has any styles applied! Now if we toggle the wrapRootElement option to true in our site/gatsby-config.js file, we'll see all of our styles get applied again.

Note that you may have to stop and restart your development server for this to take effect

Before we do anything else lets add a quick navbar component to our theme so that we can change between pages.

packages/gatsby-theme-style/src/components/navbar.js

import React from "react";
import { Link } from "gatsby";

import "../styles/navbar.css";

const Navbar = () => {
  return (
    <nav>
      <ul>
        <li>
          <Link to="/">Home</Link>
        </li>
      </ul>
    </nav>
  );
};

export default Navbar;

packages/gatsby-theme-style/src/style/navbar.css

ul {
  list-style-type: none;
  margin: 0;
  padding: 0;
  overflow: hidden;
  background-color: #333;
}

li {
  float: left;
}

li a {
  display: block;
  color: white;
  text-align: center;
  padding: 14px 16px;
  text-decoration: none;
}

li a:hover {
  background-color: #111;
}

Then lets make a few changes to our Header.css and add the component to our header as well.

packages/gatsby-theme-style/src/style/header.css

.header {
  margin: -8px;
  // CHANGED
  padding: 1.5rem 0 0 0;
  // DELETED WIDTH PROPERTY
  align-self: center;
  text-align: center;
  background-color: purple;
  font-family: Arial, Helvetica, sans-serif;
  border-bottom: solid black;
}
...

packages/gatsby-theme-style/src/components/header.js

import React from "react";
import { useStaticQuery, graphql, Link } from "gatsby";
import Navbar from "./navbar";

import "../styles/header.css";

const Header = () => {
  const data = useStaticQuery(graphql`
    query {
      site {
        siteMetadata {
          title
          description
        }
      }
    }
  `);

  return (
    <div className="header">
      <Link to="/" className="no-style">
        <h1 className="site-heading">{data.site.siteMetadata.title}</h1>
        <h4>{data.site.siteMetadata.description}</h4>
      </Link>
      <Navbar />
    </div>
  );
};

export default Header;

Now when we go to our home page we see the navbar with a link to the home page. This is where things can get a little more complicated.

We have more than just the home page in our site's pages directory, but how do we tell our theme to add those to the navbar? One way to do this is to update the options object with all of our page info.

Pass options in to our theme

Lets add a navigationPages object to our options object that will be passed in to our theme.

site/gatsby-config.js

...
  plugins: [
    {
      resolve: "gatsby-theme-style",
      options: {
        wrapRootElement: true,
        // NEW OBJECT
        navigationPages: [
          {
            name: "About",
            title: "About Us Page",
            path: "/about"
          }
        ]
      }
    }
  ]
...

Now in our theme, lets make this object accessible to our siteMetadata object.

packages/gatsby-theme-style/gatsby-config.js

module.exports = themeOptions => ({
  siteMetadata: {
    title: `Gatsby Theme Tutorial`,
    description: `A tutorial for building a GatsbyJS theme from scratch!`,
    // NEW
    navigationPages: themeOptions.navigationPages
      ? [...themeOptions.navigationPages]
      : "null"
  },
  plugins: [
    {
      resolve: `gatsby-plugin-page-creator`,
      options: {
        path: `${__dirname}/src/pages`
      }
    }
  ]
});

I'm not sure if there is a better way, but in order to allow the graphql query to fail silently we need to use a ternary operator here in order to check if this option was passed into our theme. This way if a user does not pass additional pages in to our theme package we can still query the rest of the siteMetadata without getting an error from graphql.

Lets update the static query in our header component, and then pass that data down to our navbar component.

packages/gatsby-theme-style/src/components/header.js

...
  const data = useStaticQuery(graphql`
    query {
      site {
        siteMetadata {
          title
          description
          navigationPages {
            name
            title
            path
          }
        }
      }
    }
  `);

  return (
    <div className="header">
      <Link to="/" className="no-style">
        <h1 className="site-heading">{data.site.siteMetadata.title}</h1>
        <h4>{data.site.siteMetadata.description}</h4>
      </Link>
      <Navbar navigationPages={data.site.siteMetadata.navigationPages} />
    </div>
  );
};
...

And finally lets access this new data in our navbar component and add the page to our navbar!

packages/gatsby-theme-style/components/navbar.js

...
    <nav>
      <ul>
        <li>
          <Link to="/">Home</Link>
        </li>
        {navigationPages.map((item, index) => (
          <li key={index}>
            <Link to={item.path}>{item.name}</Link>
          </li>
        ))}
      </ul>
    </nav>
...

Now we can navigate between all of the pages in our site's directory from our theme's navbar component!

This all works great if we want every page of our site to be styled by our theme, but what if we don't? How would we use the theme's style only on specific pages?

Export components from our theme to be used in our site

In order to choose to use specific components from our theme, we need to export those components from our theme package. This is done simply from inside our package's index.js file.

Currently the only line of code in this file is a comment that reads //no-op. All we have to do to allow our site to import components from our theme is add some export statements to this file.

packages/gatsby-theme-style/index.js

export { default as Layout } from "./src/components/layout";
export { default as Header } from "./src/components/header";
export { default as Navbar } from "./src/components/navbar";

Now lets change the wrapRootElement option in out site/gatsby-config.js file to false so that we can selectively choose which page will be styled with out Layout component.

site/gatsby-config.js

...
      wrapRootElement: false,
...

After restarting our development server we will see that our theme's styles are no longer applied to any of our site's pages. Lets manually apply them to our index page.

site/src/pages/index.js

import React from "react";
import { Layout } from "gatsby-theme-style";

export default () => (
  <Layout>
    <h1>Hello World!</h1>
  </Layout>
);

Just like that all of the components from our theme are now importable and able to be used by any site that is using them!

Wrapping Up

So in this part of the tutorial we changed and updated some things on our existing theme to enable our theme to play nicely with other themes that might be composed together to make up a website.

One of the things that makes Gatsby themes so appealing is the ability to compose multiple themes together. Breaking down website functionality into separate themes will allow us, as developers, to simply require a gatsby theme to add all of the functionality of a blog, or a store, or just about anything you can think of.

I'm already using a lot of these features on a regular basis, and I can say for certain that it has drastically improved my development workflow.

What's Next

In part four of this tutorial we'll begin developing a blog theme to add to our website in order to show how the compose-ability of Gatsby themes can be a game change.

Thanks for reading!

Building a GatsbyJS Theme - Part Two

Billy Jacoby — Sun, 12 May 2019 19:58:53 +0000

Designing and configuring our Layout

This is part two in a multi-part tutorial series on building your own Gatsby theme from scratch.

Please checkout the Introduction and Part One of this series if you haven't yet, as we will be picking up right where we left off at the end of part one.

The finished code for this portion of the tutorial can be found on my github repo here.

Here's what we'll be tackling in this part of the tutorial:

Create a layout component
Enable our Layout component to work across all pages
Create a Header component that gets site metadata
Put our Header in our Layout component to be shown on all pages

Create a layout component

So the first step in styling our theme is going to be building a main Layout component. We'll do this the same way you would build any other Layout component in Gatsby. We'll be building our styles in their own folders and importing them into our components. You can do the same, or use CSS in JS as well.

In your theme directory create a file named layout.js in a gatsby-theme-tutorial/src/components/ directory.

Layout components in Gatsby take in a {children} object, build their layout around this object, and render the children passed into the Layout component. This is how you would do some basic styling in a Layout component in gatsby:

All of styles are only to show how this works, we will clean all of these up in a later tutorial

/packages/gatsby-theme-tutorial/src/styles/layout.css

.container {
  margin: -8px;
  padding: 8px;
  background-color: tomato;
  font-family: Verdana, Geneva, Tahoma, sans-serif;
  width: 100%;
}

main {
  display: flex;
  height: 100vh;
  justify-content: center;
  align-items: center;
}

/packages/gatsby-theme-tutorial/src/components/layout.js

import React from "react";
import "../styles/layout.css";

const Layout = ({ children }) => {
  return (
    <div className="container">
      <main>{children}</main>
    </div>
  );
};

export default Layout;

Now the main difference in using a layout component in a normal Gatsby project, and a theme is that we want to make this layout available for all of the pages that may be built and not just the pages that come with our theme. To demonstrate this idea let's start by importing this layout file into our index.js file in our theme directory.

/packages/gatsby-theme-tutorial/src/pages/index.js

import React from "react";
import Layout from "../components/layout";

export default () => (
  <Layout>
    <h1>Hello World!</h1>
  </Layout>
);

Now lets add an About page to our site directory.

/site/src/pages/about.js

import React from "react";

const AboutPage = () => {
  return (
    <div>
      <h2>About page!</h2>
    </div>
  );
};

export default AboutPage;

Now lets start up our development server and see how our pages look.

yarn workspace site develop

After we navigate to localhost:8000 you should see that our layout has taken effect!

However, if we navigate to localhost:8000/about you'll notice that the layout isn't rendered. This is because we haven't imported the Layout component into this page.

Configuring our Layout to work across all pages

Now its possible to add our Layout component as an export to our theme package, which would enable users to import our Layout into all of the necessary pages. But we want to build a Gatsby theme to make development as easy as possible!

What we can do instead is wrap the root element of every page that gets rendered in our layout component using Gatsby's wrapRootElement. This will add our Layout component to every page created without having to import it into our page files.

Go ahead and revert your index.js back to just an H1 tag.

/packages/gatsby-theme-tutorial/src/pages/index.js

import React from "react";

export default () => <h1>Hello World!</h1>;

Next we'll create two more files in out root theme directory.

touch packages/gatsby-theme-tutorial/gatsby-browser.js

touch packages/gatsby-theme-tutorial/gatsby-ssr.js

Though it seems a little repetitive we will need to place the same code in both of these files. The reason for this is because this code will run either on the server side, or in the browser itself and regardless of where they run we still want our root element wrapped.

So both our gatsby-browser.js and gatsby-ssr.js files should contain the following code:

/packages/gatsby-theme-tutorial/gatsby-browser.js

And

/packages/gatsby-theme-tutorial/gatsby-ssr.js

import React from "react";
import Layout from "./src/components/layout";

export const wrapPageElement = ({ element, props }) => {
  // props provide same data to Layout as Page element will get
  // including location, data, etc - you don't need to pass it
  console.log(props);
  return <Layout {...props}>{element}</Layout>;
};

Now if we check both our index and about pages we should see that our layouts have rendered!

We can now begin building a site-wide header and navigation that will show up on every page, without having to import the layout component into each and every page.

Create a Header component that uses site metadata

Lets create a simple site header that displays the site name and a link to the home page.

TO do this lets add some site information to the gatsby-config.js for our theme.

/packages/gatsby-theme-tutorial/gatsby-config.js

module.exports = {
  siteMetadata: {
    title: `Gatsby Theme Tutorial`,
    description: `A tutorial for building a GatsbyJS theme from scratch!`
  },
  plugins: [
    {
      resolve: `gatsby-plugin-page-creator`,
      options: {
        path: `${__dirname}/src/pages`
      }
    }
  ]
};

Now in our Header component we need to query for our site title. We'll do this using the useStaticQuery hook that Gatsby provides. We can then take that info and use it in our component.

/packages/gatsby-theme-tutorial/src/components/header.js

import React from "react";
import { useStaticQuery, graphql, Link } from "gatsby";

import "../styles/header.css";

const Header = () => {
  const data = useStaticQuery(graphql`
    query {
      site {
        siteMetadata {
          title
          description
        }
      }
    }
  `);

  return (
    <div className="header">
      <Link to="/" className="no-style">
        <h1 className="site-heading">{data.site.siteMetadata.title}</h1>
        <h4>{data.site.siteMetadata.description}</h4>
      </Link>
    </div>
  );
};

export default Header;

/packages/gatsby-theme-tutorial/src/styles/header.css

.header {
  margin: -8px;
  padding: 1.5rem;
  width: 100%;
  align-self: center;
  text-align: center;
  background-color: purple;
  font-family: Arial, Helvetica, sans-serif;
  border-bottom: solid black;
}

.site-heading {
  font-size: 3rem;
}

.no-style {
  color: inherit;
  text-decoration: inherit;
}

This is great! Noe we can access our site metadata from our gatbsy-config.js file in our header component. The real magic happens when we add and change this file in our site folder.

/site/gatsby-config.js

module.exports = {
  siteMetadata: {
    title: `New Gatsby Site`,
    description: `A website using our Gatsby theme!`
  },
  __experimentalThemes: ["gatsby-theme-tutorial"]
};

And now the header will contain the data configured in our site folder instead of the theme folder!

Now lets add our Header to our Layout component.

Adding our Header to our Layout

All we have to do is import our header.js file into our layout.js component and place it accordingly.

/packages/gatsby-theme-tutorial/components/layout.js

import React from "react";
import "../styles/layout.css";

import Header from "./header";

const Layout = ({ children }) => {
  return (
    <div className="container">
      <Header />
      <main>{children}</main>
    </div>
  );
};

export default Layout;

Our header will now be displayed on every page created either in the site folder or the theme folder.

Wrapping Up

Building components in our Gatsby theme allows us to build fully styled components while giving the consumers of the theme control over the content with ease.

We're just scratching the surface on building this Gatsby theme, but you can already see the potential for complete customization!

If something isn't working as you would expect feel free to compare your code against the code in the repo for this part of the tutorial here.

Feel free to comment or tweet at me with any questions you might have, or with suggestions for what to cover in a future tutorial.

What's Next

In part three of this tutorial we will begin building different styles for different sections of our theme (blog, store, etc...), as well as how we can override styles and whole components from the site that is using our theme.

The possibilities are endless when it comes to end-user customization with Gatsby themes. We'll also see how little boilerplate code we need to build full websites on a Gatsby theme!

Building a GatsbyJS Theme - Part One

Billy Jacoby — Mon, 06 May 2019 23:25:55 +0000

Setting up our theme development environment

Welcome to part one of the tutorial. If you don't know what Gatsby themes are, or why you would use them, you can refer to part one of this tutorial here.

This tutorial is aimed for developers who either want to create themes to release to other users, or want to create themes that they could use across a number of their own projects.

You can view the final code for this part of the tutorial on my github page here:

Gatsby Theme - Part One

That being said, here are a few things that we will have to tackle in this part of the tutorial to get our dev environment for building themes up and running:

Initialize an 'umbrella' NPM package to contain both our theme package, as well as our development site
Initialize an NPM package that will contain all of our theme files and configurations
Initialize an NPM package that will act as a user site consuming our theme

Now bear with me, because when I first started building this theme this all seemed a little daunting, and repetitive to me.

For development purposes we will be initially building the NPM packages as private. This is so that we can use yarn's workspaces feature.

NPM Init (Thrice)

Okay so the first thing we'll do is make a directory that holds our entire theme development environment, and cd into the directory.

mkdir gatsby-theme-tutorial-development

cd gatsby-theme-tutorial-development

Once in this folder we'll run npm init for the first time. You don't need to worry about filling in the information that NPM asks you for just now. If you hit enter all the way through you should have a package.json file that looks like this:

package.json

{
  "name": "gatsby-theme-tutorial-development",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "MIT"
}

Now we need to make two changes to this file in order configure and allow us to use yarn's workspaces feature. Add the following lines to the bottom of your package.json file:

/gatsby-theme-tutorial-development/package.json

...
"private": true,
"workspaces": [
    "site",
    "packages/*"
  ]

After this is complete we need to add the mentioned directories in our gatsby-theme-tutorial folder.

mkdir packages

mkdir site

Now we cd into the packages/ folder and create the directory for our theme

cd packages

mkdir gatsby-theme-tutorial

Our folder structure will look like this so far:

gatsby-theme-tutorial-development/
--packages/
  |--gatsby-theme-tutorial/
--site/
--package.json

Now run the npm init command again in the gatsby-theme-tutorial folder, as well as the site folder. We can just hit enter through all of the prompts and worry about filling the information in later. This will make our directory structure look like this:

gatsby-theme-tutorial-development/
--packages/
  |--gatsby-theme-tutorial/
    |--package.json
--site/
  |--package.json
--package.json

Okay, now that all of that is out of the way we can begin installing the necessary dependencies for our theme. We'll be doing all of this from the main directory of our development environment, in this tutorial it will be /gatsby-theme-tutorial-development.

From this directory add the necessary dependencies to our theme workspace for Gatsby.

yarn workspace gatsby-theme-tutorial add -D gatsby react react-dom

You should see a node_modules/ folder in your gatsby theme folder once this is complete.

Now we need to copy our devDependencies to peerDependencies in the gatsby theme package.json file.

The package.json file should look like this once this is complete:

/gatsby-theme-tutorial-development/gatsby-theme-tutorial/package.json

{
  "name": "gatsby-theme-tutorial",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "MIT",
  "devDependencies": {
    "gatsby": "^2.4.2",
    "react": "^16.8.6",
    "react-dom": "^16.8.6"
  },
  "peerDependencies": {
    "gatsby": "^2.4.2",
    "react": "^16.8.6",
    "react-dom": "^16.8.6"
  }
}

Next we need to add our theme package, and our gatsby scripts to our site's package.json file. We will add this like so:

/gatsby-theme-tutorial-development/site/package.json

{
  "name": "site",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    /// NEW LINES
    "develop": "gatsby develop",
    "build": "gatsby build"
  },
  "author": "",
  "license": "MIT",
  /// NEW LINES
  "dependencies": {
    "gatsby-theme-tutorial": "*"
  }
}

The last thing we should need to do here is add our Gatsby and React dependencies to our site workspace.

yarn workspace site add gatsby react react-dom

The final package.json for our site directory should look like this now:

{
  "name": "site",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "develop": "gatsby develop",
    "build": "gatsby build"
  },
  "author": "",
  "license": "MIT",
  "dependencies": {
    "gatsby": "^2.4.2",
    "gatsby-theme-tutorial": "*",
    "react": "^16.8.6",
    "react-dom": "^16.8.6"
  }
}

Okay, take a deep breath and know that all of our boilerplate folder configuration is finally complete!

Next we just have to configure our gatsby-config.js files in order to be ready to start building!

We need to install gatsby-plugin-page-creator into our theme. To do this run the following command.

yarn workspace gatsby-theme-tutorial add gatsby-plugin-page-creator

In our gatsby-theme-tutorial folder create a gatsby-config.js file that looks like this:

gatsby-theme-tutorial/gatsby-config.js

module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-page-creator`,
      options: {
        path: `${__dirname}/src/pages`
      }
    }
  ]
};

We also need to add an index.js file into this folder so that our site recognizes this folder as an NPM package. This file doesn't need to contain anything except for a comment for now.

gatsby-theme-tutorial/index.js

// no-op

And in out site folder we need to create a super simple config file that tells our site to use our new theme!

site/gatsby-config.js

module.exports = {
  __experimentalThemes: ["gatsby-theme-tutorial"]
};

Now lets create a basic index page in our theme folder and see if everything is working as expected.

gatsby-theme-tutorial/src/pages/index.js

import React from 'react';

export default () => (
  <h1>Hello World!</h1>
);

Now to check our work...

Run yarn one last time, from our gatsby-theme-tutorial/ directory to make sure all of our packages are correctly installed.

Then run yarn workspace site develop and you will hopefully see our index page in a web browser!

The Result

Now if you're anything like me, you're probably thinking something along the lines of "Wow we needed to do all of that work just to setup an index page?"

The magic of Gatsby themes is that we can create all of our boilerplate pages and styles inside of our theme package, and any gatsby build that will be using this theme will have access to those files!

Furthermore, if we need to update a component or some styles we can do so in our theme then push the update to NPM and any other project using that theme simply has to update our theme package in order to see those updates!

If something isn't working as you would expect, remember that you can view all of the source code on the part-one branch on my Github repo for this project which can be found here.

If you get stumped feel free to comment on this post, or message me on twitter!

What's next

In part two of this tutorial we will begin diving into how we can style the layout component of our theme, and see all of those changes propagate to our development site that is using our theme.

It's going to get very interesting from here on out, so stay tuned and tweet at me or leave a comment if you get hung up on anything or have any questions!

You can view part two of the tutorial here

Building a GatsbyJS Theme - Introduction

Billy Jacoby — Mon, 06 May 2019 19:26:08 +0000

If you've been following GatsbyJS, than I'm sure you've already heard about the introduction of Gatsby themes.

Why We Need Themes

I've been building tons of sites in Gatsby lately, for both my own projects and clients. Until recently I've been using my own starter that I built to scaffold out a basic design for similar websites. This works fine, until I decide that I want to make a minor change to functionality or design across all of the sites built off of this starter.

Currently the way to do this is to make these changes, then push the same changes to all of my other sites. While this isn't the end of the world, there certainly has to be a better way to do this.

Themes to the Rescue

Gatsby themes claim to make this entire process easier by enabling a single update to a theme, that will be pushed to all sites built using that theme.

You can read more about themes directly on the GatsbyJS.org website here

Disclaimer: I have no experience with Gatsby themes yet.

I figured having no experience with themes, that this would be a great opportunity to document my path for learning about Gatsby themes, and how to build one from the ground up.

What's to Come

I will be posting my continued attempts and (hopefully) progress building a Gatsby theme.

I will link to the next parts in the tutorial as I write them for you to follow along.

Feel free to reach out via the comments, twitter, or email with any questions or requests that you might have for this tutorial!

This tutorial will be posted on both dev.to as well as my own blog, so feel free to checkout both!

Part One of the tutorial can now be found here!

IntersectionObserver API with React Hooks

Billy Jacoby — Tue, 23 Apr 2019 01:40:12 +0000

IntersectionObserver API with React Hooks

A simple demo and tutorial showing how to use the intersection observer API with React Hooks

You can view my repo for this project here.

Here is a brief synopsis of what we will do:

create-react-app
Initial project setup
- intersection-observer polyfill
- Add elements, update CSS
Write the hook
- Initialize the state
- Construct the IntersectionObserver instance
- Ensure to only observe the element intersecting once
Show the hook in action, via the console

If you want to see it in action checkout the demo here!
(be sure to have the developer console open)

We'll demonstrate how this works on a simple create-react-app skeleton.

First thing we'll do is run:

create-react-app intersection-observer-hooks

cd intersection-observer-hooks

After the initialization we'll install the polyfill for the API, to ensure support for all browsers.

yarn add intersection-observer

Next we'll add a few elements to our app, and tweak the CSS to enable us to see how everything works

App.js

...
<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 className="full-height one">
      <div className="item-one" />
    </div>
    <div className="full-height two">
      <div className="item-two" ref={elementRef}>
        {inView && <p>I'm in view!</p>}
      </div>
    </div>
    ...

App.css

... .full-height {
  height: 100vh;
  border: white dotted 1px;
  margin: 0;
  display: flex;
  align-items: center;
  justify-content: center;
}

.one {
  background-color: #61dafb;
  color: #282c34;
}

.two {
  background-color: #282c34;
  color: #61dafb;
}

.item-one {
  background-color: #282c34;
  color: #61dafb;
  height: 30%;
  width: 30%;
}

.item-two {
  color: #282c34;
  background-color: #61dafb;
  height: 30%;
  width: 30%;
}

Next we will create our hook in a separate file called useIntersectionObserver.js

The first thing we'll do in this file is configure our hook to take the necessary parameters, configure out state, and output the information we'll want to see.

useIntersectionObserver.js

import { useState, useEffect } from "react";

export const useIntersectionObserver = (
  ref,
  { threshold, root, rootMargin }
) => {
  // configure the state
  const [state, setState] = useState({
    inView: false,
    triggered: false,
    entry: undefined
  });

  return [state.inView, state.entry];
};

This hook will take a reference to the DOM node, and the options that you would like to pass in to the IntersectionObserver object; threshold, root, and rootMargin. For more information on what these options do, you can check out the MDN docs on the API here.

Now we'll configure our IntersectionObserver object, and write the callback function to update our state when our DOM node's intersectionRation is greater than 0.

useIntersectionObserver.js

...
const [state, setState] = useState({
    inView: false,
    triggered: false,
    entry: undefined
  });

  const observer = new IntersectionObserver(
    (entries, observerInstance) => {
      // checks to see if the element is intersecting
      if (entries[0].intersectionRatio > 0) {
        // if it is update the state, we set triggered as to not re-observe the element
        setState({
          inView: true,
          triggered: true,
          entry: observerInstance
        });
        // unobserve the element
        observerInstance.unobserve(ref.current);
      }
      return;
    },
    {
      threshold: threshold || 0,
      root: root || null,
      rootMargin: rootMargin || "0%"
    }
  );
...

Next we'll use React's useEffect hook to ensure that the DOM node reference exists and also to make sure that the inView state has not already been triggered as true. This will finish up our hook, the finished result should look as follows:

useIntersectionObserver.js

import { useState, useEffect } from "react";

export const useIntersectionObserver = (
  ref,
  { threshold, root, rootMargin }
) => {
  // configure the state
  const [state, setState] = useState({
    inView: false,
    triggered: false,
    entry: undefined
  });

  const observer = new IntersectionObserver(
    (entries, observerInstance) => {
      // checks to see if the element is intersecting
      if (entries[0].intersectionRatio > 0) {
        // if it is update the state, we set triggered as to not re-observe the element
        setState({
          inView: true,
          triggered: true,
          entry: observerInstance
        });
        // unobserve the element
        observerInstance.unobserve(ref.current);
      }
      return;
    },
    {
      threshold: threshold || 0,
      root: root || null,
      rootMargin: rootMargin || "0%"
    }
  );

  useEffect(() => {
    // check that the element exists, and has not already been triggered
    if (ref.current && !state.triggered) {
      observer.observe(ref.current);
    }
  });

  return [state.inView, state.entry];
};

Now that we have written our hook, its time to import it into our app and see if its working.

App.js

...
import { useIntersectionObserver } from "./useIntersectionObserver";

function App() {
  // Create the ref to our element
  const elementRef = useRef(null);
  const [inView, entry] = useIntersectionObserver(elementRef, {
    threshold: 0
  });

  // console.log our state everytime its updated to see if it works.
  useEffect(() => {
    console.log(inView);
  }, [inView]);

  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 className="full-height one">
        <div className="item-one" />
      </div>
      <div className="full-height two">
        <div className="item-two" ref={elementRef}>
          {inView && <p>I'm in view!</p>}
        </div>
      </div>
    </div>
  );
}

export default App;

Once this is all wired up, run yarn start and open your developer console. When the app first loads you should see that the state is first false, then when we scroll to the selected div, the state turns to true!

Thanks for reading and be sure to let me know if you've enjoyed this tutorial!

Shortly I'll post another that shows how to use this to animate elements onto the screen using GSAP.

Greensock Animations using React Hooks

Billy Jacoby — Sat, 20 Apr 2019 23:32:17 +0000

This is a brief tutorial on how to animate components on demand with Greensock and React hooks.

We'll be using create react app in this tutorial.

If you want to see a quick demo you can check it out here first:

https://billyjacoby.github.io/gsap-with-hooks/

To begin create a new app:

create-react-app gsap-with-hooks
cd gsap-with-hooks

The only other dependency we will need for this tutorial is GSAP.

yarn add gsap

Start the development server so that we can see our changes

yarn start

Since we will be adding our own animations here, remove the lines that animate the React Logo from src/App.css

Looking at the development server, the logo should no longer be spinning.

Now we're going to add three buttons to our app that Pause, Play, and Reverse our animation. We're also going to turn the App component into a functional component.

Your App.js should look similar to this after adding the buttons:

Okay, now for the real work. In order to accomplish this correctly only using a functional component we will need to import useState, useRef, and useEffect from react.

Replace the import React from "react"; line with:

import React, {useState, useRef, useEffect} from "react";

The first thing we'll do is create a new ref and store the react img logo in it. This will ensure that this node is loaded on the DOM before we try to animate it with Greensock.

The next thing we'll do is create a react state object to store our animation function in. This will ensure that we are always accessing the already existing animation function as opposed to creating a new one.

Next we have to use the useEffect hook to make sure that the animation is only created once the DOM has been rendered. We will create our animation function here and store it in our state object.

Since we don't want our animation to play as soon as it's loaded, we throw the .pause() method on the end of it. This will enable us to control when it starts rather than just starting on loading.

The last thing to do is to wire up our buttons to do their jobs!

Note that the reverse method basically rewinds the animation, so it will only work if the animation has been running for a few seconds.

Now this is obviously just the beginning of what you can do with react hooks and GSAP.

I'll be posting a tutorial shortly on how to use the IntersectionObserver API with GSAP to animate objects when they appear on the screen soon.

Thanks for reading, and if you're interested in any other short tutorials be sure to let me know in the comments below!