Forem: gshah2020

Build a Landing Page using Airtable as a CMS with SyncInc

gshah2020 — Mon, 26 Jul 2021 10:51:36 +0000

If you've been following along with this series, then you've come a long way. You've already mastered the essential tools and skills required to integrate Airtable as a CMS into your projects.

So before we go further, let's recap everything we've accomplished so far, shall we?

♻️ Recap

Airtable

We explored what Airtable is, and how you can use it to manage all types of data and content.

We explored the structure of Airtable and some of its core concepts such as bases, tables, records, fields. We discussed the role of foreign and private key relationships and how they're implemented under the hood in Airtable.

Next.js

We explored data-fetching strategies in Next.js and employed "static site generation" (SSG) technique to generate a fully optimized static splash page with SEO and image optimization support.

Initially using the airtable.js package we statically generated a splash page that pulls data from Airtable directly to the page.

Sync Inc

After seeing first-hand how cumbersome it is to use the airtable.js package in the second article we reached for a more scalable solution in the form of a cloud Postgres Instance synchronized with our Airtable base using SyncInc.

This allowed us to use the node-postgres package to query data from the synchronized Postgres database using raw SQL. This move not only reduced our application overhead but also helped reduce the amount of boilerplate we needed to write to achieve the same solution while significantly improving our infrastructure. With the power of a fully-provisioned Postgres instance, we now have a lot more room for scaling our application if and when it becomes necessary.

So in the end you now have an Airtable base doubling as a CMS to manage all of your content. Using SyncInc you were able to effortlessly synchronize your Airtable base with a fully provisioned Postgres database, which you can now query data from using raw SQL. And of course, you implemented lightning-fast static site generation using Next.js for optimized page builds.

⚠️ NOTE: If you're just stumbling upon this article, and much of this sounds unfamiliar to you I suggest starting at the beginning with the first article, as we cover many of these concepts in much greater detail. In either case, feel free to comment below with any questions or issues you may have!

In this article, we'll expand upon everything you've learned so far, and see how we can use those newfound skills to build an entire landing page. We'll also introduce some different techniques to explore our capabilities a bit further.

Prerequisites

Basic understanding of Javascript(ES6) and React.
General understanding of relational databases, SQL statements, and joins.
System Requirements
- Node.js 10.13 or later
- Either macOS, Windows (including WSL), or Linux

The Brief

Our client is extremely happy with the work we've done so far. They've come back to us to build out their first landing page, but they're new to content generation and are not sure what to include. They don't have a budget for copywriters at the moment so our team has introduced a novel solution.

We've offered to build out a landing page, fully generated with placeholder content that gives them a better idea of what information they should include and where on the page it makes the most sense. We're essentially providing them with a template where they can fill in the blanks.

We've ensured that all the client has to do is open up their Airtable and replace our placeholder content with their own relevant content. Our placeholder content not only acts as a placeholder but also provides useful guidance and insights into what kind of content needs to be included for each section on the page.

We've also made sure to include many of the elements that make up a high-converting landing page to give our client a better chance of success.

Project Goal

Our goal for the purpose of this article is to build out the front-end of the landing page using the placeholder content that has been generated in Airtable.

By the end of this article, you'll have built out an entire landing page using only the data from your Airtable base. And just like in the previous articles, we'll be using Next.js to statically render our page so that we can take advantage of its best-in-class SEO support and image optimization.

So before we jump in, let's take a quick look at what we'll be building. 👀

Resources

Airtable Base - This is the Airtable database you'll be working from.
Starter Repo - You can use this repo to clone our starter and follow along.
Finished Branch - Use this repo to compare your work if you run into any issues.
Project Demo - This is a working demo of the Splash page project for this project.
CodeSandbox Starter - You can also follow along using this CodeSandbox starter project.

Airtable Setup

☝️ In order to facilitate the new requirements for building out a landing page, we've made some changes to the underlying Airtable base.

Let's start by cloning this new base into your Airtable account.

Create an Airtable account or sign in to your Airtable account.
Then click here to Clone the Airtable base you'll be using for this project.

Airtable Credentials

Once you've cloned your base, you'll need both your Airtable API key and base-id to configure your application.

⚠️ NOTE: Your API key should be treated as a secret and should be kept confidential. The base-id is semi-private, but for this project, we'll be treating it as a secret as well.

☝️ If you're unsure of how to get your credentials, check out the "Airtable Credentials" section from the first article.

Once you have your Airtable credentials, let's take a look at the new structure of our Airtable data before we move on to building out the Next.js application.

Airtable Data Overview

The diagram below should look familiar to you, we went over it in detail in the first article. The red highlighted areas represent additions to the original data structure.

☝️The biggest change you'll notice is the addition of a new links table to help manage all of the links on our landing page.

Also notice that there are two new fields on the blocks table. The first, named order, is used to primarily ensure a stringent sequence when rendering several blocks within a single section as we'll soon be doing for all of our unordered bulleted lists.

Rich-Text Field

You'll also notice a new content field called bullets which is implemented as rich-text (Rich-Text is a sub-option available to any long-text type field).

Airtable implements rich-text as markdown under the hood, because this allows us to use this field type to render more complex nested content. In our case, we'll use the bullets rich-text field to render unordered bulleted lists.

For more about rich-text fields in Airtable see: Enabling rich-text

🚧 If any of the information or terminology presented above seems ambiguous to you at all then I highly recommend taking some time to review the first two articles in this series, where we discussed Airtable concepts such as tables and types in much more detail.

SyncInc Setup

If you've followed along this far, then you're already likely to have a SyncInc account from the previous article.

⚠️ If not take a look at the "SyncInc Setup" section of that article for a step-by-step guide to setting up SyncInc from scratch.

Or you can find detailed instructions in the SyncInc Docs: Connect to your Postgres Database

Once you're done with configuring SyncInc, a new Postgres database should now be available in your dashboard!

With that complete, we have all the configuration out of the way and can work to build out the front-end of the application with Next.js

Next.js Setup

Start by cloning the post3-starter branch.

git clone -b post3-starter https://github.com/gaurangrshah/next-airtable-splash.git

Once again we're cloning a specific branch so that you can take advantage of some pre-built components and default styling already applied for you.

Hopefully, this allows us to maintain focus on the core goals of this project.

Navigate to the project directory.

   cd next-airtable-splash

Install project dependencies.

   yarn

Once your packages have been installed. Go ahead and spin up your development server and ensure that the application is running properly.

   yarn dev

If all goes well you should see the completed splash page from the first two parts of this project. ![015]

In this article, we'll be building out a new page route /landing which will render the data from our landing page.

Once you're sure the project is running and you're able to load the application let's take a moment to familiarize yourself with this starter template.

.
├── README.md
├── components
│   ├── Containers.js
│   ├── Link.js
│   ├── MarkdownJsx.js
│   ├── SEO.js
│   ├── landing
│   │   ├── BenefitsCards.js
│   │   ├── BrandList.js
│   │   ├── Card.js
│   │   ├── FeaturedBenefit.js
│   │   ├── FooterCta.js
│   │   ├── Header.js
│   │   ├── Hero.js
│   │   ├── Pricing.js
│   │   ├── RiskCta.js
│   │   ├── SectionHeading.js
│   │   ├── Testimonial.js
│   │   └── index.js
│   └── splash
│       ├── Cta.js
│       ├── Hero.js
│       ├── List.js
│       └── index.js
├── lib
├── next.config.js
├── package.json
├── pages
│   ├── _app.js
│   ├── api
│   │   └── hello.js
│   ├── index.js
├── public
│   ├── check.png
│   ├── favicon.ico
│   ├── logo-holder.svg
│   └── vercel.svg
├── styles
│   ├── Containers.module.css
│   ├── Home.module.css
│   ├── Landing.module.css
│   ├── Markdown.module.css
│   ├── globals.css
│   ├── landing
│   │   ├── BrandList.module.css
│   │   ├── Card.module.css
│   │   ├── FeaturedBenefits.module.css
│   │   ├── FooterCta.module.css
│   │   ├── Header.module.css
│   │   ├── Hero.module.css
│   │   ├── Pricing.module.css
│   │   ├── RiskCta.module.css
│   │   ├── SectionHeading.module.css
│   │   └── Testimonial.module.css
│   ├── normalize.css
│   └── splash
│       ├── Cta.module.css
│       ├── Hero.module.css
│       └── List.module.css
├── utils
│   └── data-helpers.js
└── yarn.lock

Just like in the previous articles, you'll find that the starter also includes all of the styles and each of the components you'll need for this project including a few helper functions that will make handling the data a bit simpler.

Environment Variables

The next thing you'll need to do is add your environment variables used to connect to your SyncInc Postgres instance. You should already have a .env.sample file at the root of your project, simply rename this to .env.local, and fill in the values from your SyncInc dashboard.

# .env.local

DB_USER=
DB_HOST=
DB_NAME=
DB_PW=
DB_PORT=

From your SyncInc dashboard click the "Connect" button.

You'll need to fill in the corresponding values from the credentials tab of the SyncInc dashboard

Connect to your Sync Inc Database

The next logical step for us to is to take a look at how we're fetching data from Airtable using SyncInc's Postgres instance.

In this article, we've taken a bit of a different approach where in the last article we used a single Postgres client instance, we're now implementing a pool of clients, which is the preferred method for allowing multiple database connections each with their own client instance and allows our connection to scale according to our needs. Let's take a look at how this works in your /lib/pg-pool.js file:

// /lib/pg-pool.js

const { Pool } = require("pg");
// @link: https://node-postgres.com/guides/project-structure
// @link: https://node-postgres.com/guides/async-express

const pool = new Pool({
  // configure database (* optional)
  host: process.env.DB_HOST,
  port: process.env.DB_PORT,
  user: process.env.DB_USER,
  password: process.env.DB_PW,
  database: process.env.DB_NAME,
});

// retains count for number of connections established
let count = 0;

// used to log each pool connection
pool.on("connect", (client) => {
  client.count = count++;
  console.log(`clients connected: ${count}`);
});

// export an async query, which takes in necc. args.
module.exports = {
  // query from pooled connection
  async query(text, params) {
    const start = Date.now(); // get starting time
    // connect to pool
    const client = await pool.connect();
    const res = await client.query(text, params);
    client.release();
    const duration = Date.now() - start; // get elapsed time

    // log results
    console.log("executed query", {
      /* text, params, */
      duration,
      rows: res.rowCount,
    });
    return res; // return results
  },
};

This has already been implemented for you in order to ensure that the splash page we built in the last project still remains functional.

There's quite a bit going on here, but I think the comments provide a good amount of context. In either case, let's talk about how this differs from our initial approach.

PG Pool vs PG Client

Originally we used a Postgres client directly to query for our data and that works well for a single query. But for our use case, we'll need to make a separate query for each static page we want to generate at build-time in our application. The client will normally throw an error because essentially we're trying to re-use the same client for different queries.

For more information see: When to use a Pool vs a Client

Now with our new approach, we first initialize a pool and then derive the client from that pool, so each time get a new client for each query, which means we can run several queries in parallel if we need to.

// configures postgres pool
const pool = new Pool({
  // configure database (* optional)
  host: process.env.DB_HOST,
  port: process.env.DB_PORT,
  user: process.env.DB_USER,
  password: process.env.DB_PW,
  database: process.env.DB_NAME,
});

Using the pool we're also able to provide better logging, currently we've set up an event listener that fires on each new client connection and logs the details for that connection.

// used to log each pool connection on each `connect` event
pool.on("connect", (client) => {
  client.count = count++;
  console.log(`clients connected: ${count}`);
});

And finally we export an async query function which we use as a wrapper to connect to a new client from our pool.

// export an async query, which takes in necc. args.
module.exports = {
  // query from pooled connection
  async query(text, params) {
    const start = Date.now(); // get starting time
    // connect to pool and derive client
    const client = await pool.connect();
    const res = await client.query(text, params);
    client.release();
    const duration = Date.now() - start; // get elapsed time

    // log results
    console.log("executed query", {
      /* text, params, */
      duration,
      rows: res.rowCount,
    });
    return res; // return results
  },
};

This function also takes in two arguments, text and params. The text is the actual raw SQL query statement while the params are any optional arguments that our query uses as variables to find and filter through our Postgres data.

Querying

You'll notice that we're still able to use the exact same query, to get our data for our splash page.

// lib/queries.js

export const SECTIONS_QUERY = `SELECT
      p.id AS page_id,
      p.title AS page_title,
      p.path AS page_path,
      p.order_ AS page_order,
      p.sectionid As page_sections_id,
      p.seoid AS page_seo_id,
      s.id AS section_id,
      s.title AS section_title,
      s.order_ AS section_order,
      s.type AS section_type,
      s.filter AS section_filter,
      s.blockid AS section_block_id,
      s.pageid AS section_page_id,
      b.id AS block_id,
      b.title AS block_title,
      b.lead AS block_lead,
      b.excerpt AS block_excerpt,
      b.content AS block_content,
      b.mediaid AS block_media_id,
      b.sectionid AS block_section_id,
      m.id AS media_id,
      m.title AS media_title,
      m.url AS media_url,
      m.alt AS media_alt,
      m.blockid AS media_block_id,
      m.seoid AS media_seo_id,
      seo.id AS seo_id,
      seo.title AS seo_title,
      seo.description AS seo_description,
      seo.keywords AS seo_keywords,
      seo.sitename AS seo_sitename,
      seo.url AS seo_url,
      seo.mediaid AS seo_media_id,
      seo.pageid AS seo_page_id
    FROM
      pages AS p 
      LEFT JOIN seo ON seo.id = ANY (p.seoid)
      LEFT JOIN sections AS s ON s.id = ANY (p.sectionid)
      LEFT JOIN blocks AS b ON b.id = ANY (s.blockid)
      LEFT JOIN media AS m ON m.id = ANY (b.mediaid)
    WHERE
      p.title IN ('launch')
    ORDER BY p.id ASC, s.order_ ASC`;

The one major difference is that now we're using our Pool connection rather than the Client to execute our query.

// lib/pg.js

const db = require("./pg-pool");

const { SECTIONS_QUERY } = require("./queries");

async function getSections() {
  // used for the Splash Page =>  airtable data
  try {
    // query database for sections and all related data.
    const res = await db.query(SECTIONS_QUERY);

    // handle success
    return res;
  } catch (err) {
    // handle errors
    console.error(err);
  }
}

module.exports = {
  getSections,
};

Now that we understand how our pooled connections are helping us manage our SQL queries, we can turn our attention to building out the SQL query we'll need to get the data for our landing page.

Let's open up our database management tool.

☝️ If you've been following along you'll recall we did the same thing in the last article using Table Plus, but you can use any database management tool that supports Postgres and can execute queries.

⚠️ If you need instructions on the setup again, you can also refer to SyncInc's guide: Connecting to your Postgres database.

You can use your database management tool to build out and test our new query against your actual database.

Once you've set up the connection to your new Postgres database, go ahead and copy the query below and paste it into a new query file as shown in the screenshot below, and be sure to "save".

SELECT
    p.id AS page_id,
    p.title AS page_title,
    p.sectionid AS page_sections_id,
    p.seoid AS pages_seo_id,
    s.id AS section_id,
    s.title AS section_title,
    s.order_ AS section_order,
    s.type AS section_type,
    s.filter AS section_filter,
    s.blockid AS section_block_id,
    b.id AS block_id,
    b.order_ AS block_order,
    b.title AS block_title,
    b.lead AS block_lead,
    b.excerpt AS block_excerpt,
    b.content AS block_content,
    b.bullets AS block_bullets,
    b.mediaid AS block_media_id,
    b.linkid AS block_link_id,
    m.id AS media_id,
    m.title AS media_title,
    m.url AS media_url,
    m.alt AS media_alt,
    m.blockid AS media_block_id,
    m.seoid AS media_seo_id,
    links.id AS link_id,
    links.title AS link_title,
    links.description AS link_description,
    links.href AS link_href,
    links.type AS link_type,
    links.is_external AS link_is_externla,
    links.blockid AS link_block_id,
    seo.id AS seo_id,
    seo.title AS seo_title,
    seo.description AS seo_description,
    seo.keywords AS seo_keywords,
    seo.sitename AS seo_sitename,
    seo.url AS seo_url,
    seo.mediaid AS seo_media_id
FROM
    pages AS p
    LEFT JOIN seo ON seo.id = ANY (p.seoid)
    LEFT JOIN sections AS s ON s.id = ANY (p.sectionid)
    LEFT JOIN blocks AS b ON b.id = ANY (s.blockid)
    LEFT JOIN media AS m ON m.id = ANY (b.mediaid)
    LEFT JOIN links ON links.id = ANY (b.linkid)
WHERE
    p.title IN('landing')
ORDER BY
    s.order_ ASC;

Once you've saved your query click on the file you just created in the sidebar to load your query into the editor then click the Run current button (as shown below) to execute your query.

You should now see your query has been executed, and at the bottom of the window, it shows that the database returned 27 rows of data.

If you look closely at this new query below, you'll notice that we're using an argument at the end inside of the WHERE clause to help target the specific page we want the data for.

Up until now we only had data for one page, so we didn't have to make that distinction, but now that we have data for multiple pages, it makes sense to only fetch the data we need for each page specifically.

We'll also want to be able to re-use this query for any page, so we'll take a look at how we can provide the value for each page as an argument using a wrapper function to handle the query for us.

Now that we've tested our query and we know how it works, let's implement it in our application:

// lib/queries.js

export const GET_PAGE_QUERY = `SELECT
    p.id AS page_id,
    p.title AS page_title,
    p.sectionid AS page_sections_id,
    p.seoid AS pages_seo_id,
    s.id AS section_id,
    s.title AS section_title,
    s.order_ AS section_order,
    s.type AS section_type,
    s.filter AS section_filter,
    s.blockid AS section_block_id,
    b.id AS block_id,
    b.order_ AS block_order,
    b.title AS block_title,
    b.lead AS block_lead,
    b.excerpt AS block_excerpt,
    b.content AS block_content,
  b.bullets AS block_bullets,
    b.mediaid AS block_media_id,
    b.linkid AS block_link_id,
    m.id AS media_id,
    m.title AS media_title,
    m.url AS media_url,
    m.alt AS media_alt,
    m.blockid As media_block_id,
    m.seoid AS media_seo_id,
    links.id AS link_id,
    links.title AS link_title,
    links.description AS link_description,
    links.href AS link_href,
    links.type AS link_type,
    links.is_external AS link_is_externla,
    links.blockid AS link_block_id,
    seo.id AS seo_id,
    seo.title AS seo_title,
    seo.description AS seo_description,
    seo.keywords AS seo_keywords,
    seo.sitename AS seo_sitename,
    seo.url AS seo_url,
    seo.mediaid AS seo_media_id
FROM
    pages AS p
    LEFT JOIN seo ON seo.id = ANY (p.seoid)
    LEFT JOIN sections AS s ON s.id = ANY (p.sectionid)
    LEFT JOIN blocks AS b ON b.id = ANY (s.blockid)
    LEFT JOIN media AS m ON m.id = ANY (b.mediaid)
    LEFT JOIN links ON links.id = ANY (b.linkid)
WHERE
    p.title IN($1)
ORDER BY s.order_ ASC`;

Once again, if you look closely you'll notice that we're no longer hard-coding in our page name like we did when testing our query in Table Plus. Instead, we've created a SQL variable with the $1 syntax inside of the WHERE clause. This allows us to populate this query with the title of the page that we need data for.

And since we expect the same data shape for each page we can easily make this query reusable.

Now we can supply our variable to the query from a custom wrapper function:

// lib/pg.js

const { GET_PAGE_QUERY } = require("./queries");

/*  content truncated for brevity  */

// get all page data for a single page and returns Airtable data
async function getPage(page = "landing") {
  // defaults to landing page, 
  try {
    // query database uwing query argument: page
    // lists all records related to a specific page
    return db.query(GET_PAGE_QUERY, [page]);

    // handle success
  } catch (err) {
    console.error(err);
  }
}

// be sure to export the getPage function:
module.exports = {
  getSections,
  getPage,
};

NOTE: Although the current GET_PAGE_QUERY only declares a single variable, we can actually define as many as we need for our queries.

As you can see from the following:
return db.query(GET_PAGE_QUERY, [page]); // 2nd arg: [params]
The 2nd argument to the query method takes an array of params, used to populate the values for the variables in our query. In our case, this is the title of the page we are querying for.

Currently, we only have that single variable declared within our query so we only need to populate the array with a single param, but you could just as easily declare multiple variables and then include multiple params in the array when necessary.

Each of the params maps to a variable by its position in the array. So the first param maps to $1 and the next would map to $2 and so on for as many variables you need to declare.

With our query wrapper function in place, we can now use it to get the data we need to render our landing page.

Static Site Generation

As we saw in the previous articles, we can use the built-in data-fetching methods provided by Next.js to grab any data we need at build time to help render our static pages.

Although there are many useful ways to fetch and handle data in a Next.js application, we've been using the getStaticProps() function to asynchronously grab our data while our page is being built.

We're going to do the same thing here. We'll be using the wrapper function we created getPage() to query our cloud Postgres instance for the data we need.

🕥 *RECALL: * Next.js automatically executes any logic defined in getStaticProps() function from any Page Component file at build-time.

Jump Ahead😎

If you're confident with Next.js and what you've learned so far, I urge you to give the following a try on your own.

Create a new file pages/landing.js for your landing page.

Create and export a default Page Component from the /landing.js page file.

Navigate to your page in the browser (http://localhost:3000/landing) and make sure you don't have any 404 errors.

Now export an asynchronous getStaticProps() function and asynchronously import your getPage() function inside of it.

Execute the getPage() function and only return the rows array from the response as props from getStaticProps().

Handle the props you returned from getStaticProps() in your Page Component and use JSON.stringify(props.rows) to dump the data out onto the page.

⚠️ Spoiler Warning

Ok let's go through it together:

First, let's create a new file in the pages directory where you can define your Landing Page Component.

// pages/landing.js

export default function Landing({ page }) {
  return page && <div>{JSON.stringify(page)}</div>;
}

☝️ Remember to make sure that the Page Component is the default export from this file.

Next, let's define our asynchronous getStaticProps() function.

// pages/landing.js

export default function Landing({ page }) {
  return page && <div>{JSON.stringify(page)}</div>;
}

export async function getStaticProps() {

  return {
    props: {
      page: [];
    },
  };
}

Now we can implement our data fetching logic inside of the getStaticProps() function.

// pages/landing.js

export default function Landing({ page }) {
  return page && <div>{JSON.stringify(page)}</div>;
}

export async function getStaticProps() {
  const { getPage } = await import("../lib/pg");

  const response = await getPage("landing");
  return {
    props: {
      page: response.rows;
    },
  };
}

If you were successful in fetching the data and dumping it onto the page, then your results should be similar to what you see in the screenshot below:

Before we go any further let's examine the data we get back from querying our Postgres database in our console.

We seem to get back exactly 21 rows of data. If we dig a bit further we see that the shape of our data is flat, we haven't maintained any sort of hierarchy in our data. Which is expected, but is still something we'll want to address.

In the last article, we used a factory function to transform our data, and we'll do the same here. Although this time it is a bit different in that, we'll be using several factory functions together.

We'll pass our page data through the PageBuild() function before we return it from getStaticProps() as props.

Let's take a look at the PageBuild() function to see what it does for us - open up the file utils/data-helpers.js:

// utils/data-helpers.js

export function PageBuild(rows) {
  // transforms page data
  const seo = new Seo(rows[0]);
  return {
    seo,
    page: rows?.length && rows?.map((row) => new Row(row)),
  };
}

From the code block above, it's clear that most of the logic that actually handles the transforms is defined within the Seo() factory function, and the logic that transforms the page rows is likely defined in the Row() factory function.

⚠️ Both of these factory functions are located in the same file, feel free to browse through them so that you understand how the data is being transformed, it's quite straight forward so we're going to skip over displaying them here. But here's how they're implemented in our PageBuild() function...

First, we grab the first item of the rows array and simply pluck out the SEO-related metadata for this page using the Seo() factory function.

Next, we iterate over each item in the rows array and return a new row in the exact shape that we expect our data to be in using the Row() factory function.

We then return both the seo object and page array back.

Now let's take a look at how we implement this inside of the getStaticProps() function:

// pages/landing.js

import { PageBuild } from "../utils/data-helpers";

export default function Landing({ page }) {
  return <div>{JSON.stringify(page)}</div>;
}

export async function getStaticProps() {
  const { getPage } = await import("../lib/pg");

  const response = await getPage("landing");
  const page = PageBuild(response?.rows);

  return {
    props: {
      page,
    },
  };
}

With this in place, all the hard work is done, we've successfully set up our getStaticProps() function and implemented all of the data-fetching logic we'll need.

Now we can work to simply render each of these items from the page array.

UI/UX

As with the previous articles in this series, you already have all of the components and styles you need to render the data pre-fabricated for you in the components in the components/landing directory.

.
├── components
│   ├── Containers.js
│   ├── Link.js
│   ├── MarkdownJsx.js
│   ├── SEO.js
│   ├── landing
│   │   ├── BenefitsCards.js
│   │   ├── BrandList.js
│   │   ├── Card.js
│   │   ├── FeaturedBenefit.js
│   │   ├── FooterCta.js
│   │   ├── Header.js
│   │   ├── Hero.js
│   │   ├── Pricing.js
│   │   ├── RiskCta.js
│   │   ├── SectionHeading.js
│   │   ├── Testimonial.js
│   │   └── index.js

All you have to do is structure the page accordingly and use these components to render the appropriate section of the page.

👀 NOTE: If you haven't done so already be sure to take a look at the Project Demo so you have a better idea of what you're building.

SEO

Let's start at the beginning, with our SEO component. Unlike the previous articles, this time around we'll be using a custom SEO component that has already been created for you, but let's take a look at the component itself, and see what it does for us.

// components/SEO.js

import Head from "next/head";

export const SEO = ({ seo }) => {
  return (
    <Head>
      <title>{seo.title}</title>
      <meta name='viewport' content='initial-scale=1.0, width=device-width' />
      <meta name='description' content={seo.description} />
      <meta property='og:title' content={seo.title} />
      <meta property='og:site_name' content={seo.sitename} />
      <meta property='og:url' content={seo.url} />
      <meta property='og:description' content={seo.description} />
      <meta property='og:image' content={seo.url} />
      <link rel='icon' href='/favicon.ico' />
      <link rel='cannonical' href={seo.url} />
    </Head>
  );
};

The SEO component takes in a single prop - - a seo object, and we then use it to populate all of the metadata for our page.

Implementing the SEO component is pretty straightforward thanks to our factory functions that shaped our data for us.

// pages/landing.js

import { SEO } from "../components/SEO";

export default function Landing({ page }) {
  const { seo, page: rows } = page;

  return (
    <>
      <SEO seo={seo} />
      <div>{JSON.stringify(page)}</div>;
    </>
  );
}

With this in place, you should see the title of your page has changed indicating that we've successfully implemented our SEO metadata for this page.

So far so great, let's move on and set up a bit of the boilerplate for the landing page.

// pages/landing.js

import { Header } from "../components/landing";

import styles from "../styles/Landing.module.css";

export default function Landing({ page }) {
  const { seo, page: rows } = page;

  return (
    <>
      <SEO seo={seo} />
      <div className={styles.pageWrapper}>
        <Header brandName={seo?.title} />
        <main className={styles.main}>Test</main>
        <footer className={styles.footer}>
          {" "}
          &copy;
          <span>Uptime Sentry</span> {new Date().getFullYear()}
        </footer>
      </div>
    </>
  );
}

You should now be able to see your header and footer rendered out accordingly.

Now before we get back to rendering our data, we'll need to transform it one step further, by sorting our rows logically, by their titles. Rows with matching titles will get grouped together as a single row, this helps us flatten sections that use multiple blocks to render the appropriate data.

First, let's take a look at the helper functions we'll use to apply our sorting logic:

// utils/data-helpers.js

export function groupBy(arr, key) {
  // groups objests in array into grouped arrays based on matching key
  return arr.reduce(function (rv, x) {
    (rv[x[key]] = rv[x[key]] || []).push(x);

    return rv;
  }, {});
}

export function sortRows(rows) {
  // used to group and camelCase an array of airtable rows, by their matching titles
  const interim = groupBy(rows, "title");
  return Object.keys(interim)?.map((key) => {
    const newKey = camelize(key);
    return {
      [newKey]: interim[key],
    };
  });
}

sortRows() takes in all of our rows and iterates over them using the groupBy() function to group them by matching titles which results in a single object for each row with the title of each row used as the key. We then take that object, and transform the keys from the kebab-cased titles to camel-cased property names and finally return an array of sorted rows.

// pages/landing.js

import { PageBuild, sortRows } from "../utils/data-helpers";

export default function Landing({ page }) {
  const { seo, page: rows } = page;
  const sortedRows = sortRows(rows);
  console.log("🚀 ~ file: landing.js sortedRows", sortedRows)

  return (
    <>
            {/* truncated for brevity */}
    </>
  );
}

Now let's take a look at the sorted data in your console:

Now that we have our data properly sorted, let's turn our focus back to rendering it out, starting with the Hero component, where we'll just de-structure the data we need right from the sortedRows array.

import { Container, Section, Row } from "../components/Containers";
import { Header, Hero } from "../components/landing";

export default function Landing({ page }) {
  const { seo, page: rows } = page;

  // pluck the hero component's data out of the array.
  const [{landingHero}] = sortRows(rows); 

  return (
    <>
      <SEO seo={seo} />
      <div className={styles.pageWrapper}>
        <Header brandName={seo?.title} />

            <Section style={{ padding: "2em", textAlign: "center" }}>
          <Hero block={landingHero[0]?.block} />
        </Section>

        <footer className={styles.footer}>
          {" "}
          &copy;
          <span>Uptime Sentry</span> {new Date().getFullYear()}
        </footer>
      </div>
    </>
  );
}

We simply pass in the block related to the Hero component as props, the component will handle the rest.

👀 If you're curious as to what the Hero component is doing, feel free to take a look at the file: components/landing/Hero.js, but once again since it's pretty straightforward, we're not going to go over it in detail here.

The next component we'll want to render is the BrandList component that we use as social proof.

// pages/landing.js

import { BrandList, Header, Hero } from "../components/landing";


export default function Landing({ page }) {
  const { seo, page: rows } = page;
  const [{ landingHero }, { landingBrandList }] = sortRows(rows);

  return (
    <>
      <SEO seo={seo} />
      <div className={styles.pageWrapper}>
        <Header brandName={seo?.title} />
        <main className={styles.main}>
          <Section style={{ padding: "2em", textAlign: "center" }}>
            <Hero block={landingHero[0]?.block} />

            <Container>
              <BrandList data={landingBrandList} />
            </Container>

          </Section>
        </main>
        <footer className={styles.footer}>
          &copy;
          <span>Uptime Sentry</span> {new Date().getFullYear()}
        </footer>
      </div>
    </>
  );
}

Once again this is a simple component, but you can dig further: components/landing/BrandList.js

The next component actually renders two of our sections at once:

// pages/landing.js

import { BenefitsCards, BrandList, Header, Hero } from "../components/landing";

export default function Landing({ page }) {
  const { seo, page: rows } = page;

  const [
    { landingHero },
    { landingBrandList },
    { landingBenefitsIntro },
    { landingBenefits },
  ] = sortRows(rows);

  return (
    <>
      <SEO seo={seo} />
      <div className={styles.pageWrapper}>
        <Header brandName={seo?.title} />
        <main className={styles.main}>
                {/* truncated for brevity */}

          <Section className='secondary-light'>
            <BenefitsCards
              headingBlock={landingBenefitsIntro[0].block}
              // sort by block order ASC
              data={landingBenefits.sort((a, b) =>
                a.block.order > b.block.order ? 1 : -1
              )}
            />
            </Section>

        </main>

        {/* truncated for brevity */}
      </div>
    </>
  );
}

The BenefitsCards components render both the landingBenefitsIntro and landingBenefits sections.
☝️You might've noticed that we sort the data according to the block.order field before we pass it in as props.

We'll also include the featuredTestimonial in this same section, but first, we de-structure it off of the landingFeaturedTestimonial array.

// pages/landing.js

import {
  BenefitsCards,
  BrandList,
  Header,
  Hero,
  Testimonial,
} from "../components/landing";

export default function Landing({ page }) {
  const { seo, page: rows } = page;

  const [
    { landingHero },
    { landingBrandList },
    { landingBenefitsIntro },
    { landingBenefits },
    { landingFeaturedTestimonial },
  ] = sortRows(rows);

  // we'll be using this in multiple places, so we'll store it for easy access.
  const [featuredTestimonial] = landingFeaturedTestimonial;

  return (
    <>
      <SEO seo={seo} />
      <div className={styles.pageWrapper}>
        <Header brandName={seo?.title} />
        <main className={styles.main}>
                {/* truncated for brevity */}

          <Section className='secondary-light'>
            <BenefitsCards
              headingBlock={landingBenefitsIntro[0].block}
              data={landingBenefits.sort((a, b) =>
                a.block.order > b.block.order ? 1 : -1
              )}
            />

            <Testimonial block={featuredTestimonial.block} />

            </Section>

        </main>

        {/* truncated for brevity */}
      </div>
    </>
  );
}

Next up we have 3 FeaturedBenefit blocks in total that we'll render accordingly:

// pages/landing.js

import {
  BenefitsCards,
  BrandList,
  FeaturedBenefit,
  Header,
  Hero,
  Testimonial,
} from "../components/landing";

export default function Landing({ page }) {
  const { seo, page: rows } = page;

  const [
    { landingHero },
    { landingBrandList },
    { landingBenefitsIntro },
    { landingBenefits },
    { landingFeaturedTestimonial },
    { landingFeaturedBenefit1 },
    { landingFeaturedBenefit2 },
    { landingFeaturedBenefit3 },
  ] = sortRows(rows);

  // we'll be using this in multiple places, so we'll store it for easy access.
  const [featuredTestimonial] = landingFeaturedTestimonial;

  return (
    <>
      <SEO seo={seo} />
      <div className={styles.pageWrapper}>
        <Header brandName={seo?.title} />
        <main className={styles.main}>
                {/* truncated for brevity */}

          <Section>
            <Container>
              <FeaturedBenefit
                block={landingFeaturedBenefit1[0].block}
                alternate={landingFeaturedBenefit1[0]["filter"].includes(
                  "reverse"
                )}
              />
            </Container>
            <div style={{ width: "100%", background: "var(--primary-light)" }}>
              <Container>
                <FeaturedBenefit
                  block={landingFeaturedBenefit2[0].block}
                  alternate={landingFeaturedBenefit2[0]["filter"].includes(
                    "reverse"
                  )}
                />
              </Container>
            </div>
            <Container>
              <FeaturedBenefit
                block={landingFeaturedBenefit3[0].block}
                alternate={landingFeaturedBenefit3[0]["filter"].includes(
                  "reverse"
                )}
              />
            </Container>
          </Section>

        </main>

        {/* truncated for brevity */}
      </div>
    </>
  );
}

Each of the FeaturedBenefit components takes in the block it will render as a prop. As well as an alternate prop that is used to determine which item's layout will get flipped in our UI.

We use the sections.filter field to designate the block that will get rendered with an alternate layout.

Rendering Markdown

Let's take a moment to discuss how this component is being rendered. Particularly how we're rendering the rich text for the bullets field.

We discussed how the rich text fields are delivered to us as a markdown string. Now let's take a look at how we can render that markdown content.

// components/landing/FeaturedBenefit.js

import Image from "next/image";

import { Row } from "../Containers";
import { MarkdownJSX } from "../MarkdownJsx";

import styles from "../../styles/landing/FeaturedBenefits.module.css";

export const FeaturedBenefit = ({ block, alternate, data }) => {
  return (
    <>
      <Row
        className={[styles?.benefit, alternate ? styles?.alternate : ""].join(
          " "
        )}
        data-test={data}
      >
        <Image
          src={block?.media?.url[0]}
          alt={block.media?.alt}
          layout='intrinsic'
          width={1180}
          height={920}
        />

        <div className={styles.content}>
          <h3>{block.title}</h3>
          <p>{block.excerpt}</p>
          <MarkdownJSX
            className={styles.markdown}
            markdown={block.bullets}
            overrides={{
              ul: (props) => <ul className={styles.ul} {...props} />,
              li: (props) => <li className={styles.li} {...props} />,
            }}
          />
        </div>
      </Row>
    </>
  );
};

For the most part, this component is like any other, but you might not be familiar with our approach to rendering our bulleted lists from markdown content.

We use a custom component called MarkdownJSX which is essentially a wrapper around the third-party library: markdown-to-jsx.

// components/MarkdownJsx.js

import Markdown from "markdown-to-jsx";
import styles from "../styles/Markdown.module.css";
export const MarkdownJSX = ({
  markdown = "",
  type = "list",
  highlight = false,
  overrides,
  ...rest
}) => {
  return (
    <Markdown
      className={styles.markdown}
      {...rest}
      options={{
        overrides: {
          // overrides allow defining of specific components to be used to render each element
          span: (props) => (
            <span className={styles.span} {...props} {...rest.span} />
          ),
          ul: (props) => <ul className={styles.ul} {...props} {...rest.ul} />,
          li: (props) => (
            <li
              className={styles.li}
              style={highlight ? { ...highlightStyles } : {}}
              {...props}
              {...rest.li}
            />
          ),
        },
      }}
    >
      {markdown}
    </Markdown>
  );
};

const highlightStyles = {
  fontWeight: "bold",
  fontSize: "medium",
};

This component takes in a markdown prop that expects "stringified" markdown content. We then take that markdown content and render it as a child of the component.

The options object of our Markdown component is where all the magic happens. This is where we define custom components used as overrides to render each of the elements we expect to be passed in as markdown content.

Since we're only using markdown for the sole purpose of rendering out our unordered bulleted lists, we've only provided 3 custom components.

span for situations where our content is wrapped in a span
ul for the unordered list
li for each of the list items.

With this logic, we're able to target and style each of the elements that get output from our markdown content and override those styles in-line when we need to.

Now that you have a good grasp of how we're using the markdown-to-jsx package to help render our bulleted lists from the rich-text content we get back from Airtable, let's move on to rendering our last few sections of this page.

The next component we need to render is the RiskCta, the only caveat here is that we're still rendering it inside the same section element as the FeaturedBenefit components.

// pages/landing.js

import {
  BenefitsCards,
  BrandList,
  FeaturedBenefit,
  Header,
  Hero,
  RiskCta,
  Testimonial,
} from "../components/landing";

export default function Landing({ page }) {
  const { seo, page: rows } = page;
  const [
    { landingHero },
    { landingBrandList },
    { landingBenefitsIntro },
    { landingBenefits },
    { landingFeaturedTestimonial },
    { landingFeaturedBenefit1 },
    { landingFeaturedBenefit2 },
    { landingFeaturedBenefit3 },
    { landingCtaRisk },
  ] = sortRows(rows);

  const [featuredTestimonial] = landingFeaturedTestimonial;

 return (
    <>
      <SEO seo={seo} />
      <div className={styles.pageWrapper}>
        <Header brandName={seo?.title} />
        <main className={styles.main}>
                {/* truncated for brevity */}

          <Section>

            {/* truncated for brevity */}

            {/* 
            ☝️ the RiskCta component gets rendered in the same section as FeaturedBenefits                       */}

            <div style={{ width: "100%", background: "var(--secondary-light)" }}>
                <RiskCta block={landingCtaRisk[0].block} />
              </div>

          </Section>

        </main>

        {/* truncated for brevity */}
      </div>
    </>
  ); 

}

// pages/landing.js

import {
  BenefitsCards,
  BrandList,
  FeaturedBenefit,
  Header,
  Hero,
  Pricing,
  RiskCta,
  Testimonial,
} from "../components/landing";

export default function Landing({ page }) {
  const { seo, page: rows } = page;
  const [
    { landingHero },
    { landingBrandList },
    { landingBenefitsIntro },
    { landingBenefits },
    { landingFeaturedTestimonial },
    { landingFeaturedBenefit1 },
    { landingFeaturedBenefit2 },
    { landingFeaturedBenefit3 },
    { landingCtaRisk },
    { landingPricing },
  ] = sortRows(rows);

  const [featuredTestimonial] = landingFeaturedTestimonial;

 return (
    <>
      <SEO seo={seo} />
      <div className={styles.pageWrapper}>
        <Header brandName={seo?.title} />
        <main className={styles.main}>
                {/* truncated for brevity */}


            <Section>
              <Container>
                <Pricing data={landingPricing} />
              </Container>
            </Section>

        </main>

        {/* truncated for brevity */}
      </div>
    </>
  ); 

}

The Pricing component also renders a markdown list just like we did with the FeaturedBenefit Component. And we implement a bit of logic to emphasize the perferred pricing plan by styling it just a bit differently to make it stand out amongst the rest of the options.

The final Pricing component is rendered using several smaller components which allows us to offload some of the rendering responsibility to components where it makes sense.

// components/landing/Pricing.js

import { Link } from "../Link";
import { Container, Row } from "../Containers";
import { MarkdownJSX } from "../MarkdownJsx";

import styles from "../../styles/landing/Pricing.module.css";

export const PricesHeading = ({ block }) => {
  return (
    <Container className={styles.prices_heading}>
      <h2>{block.title}</h2>
      <p>{block.excerpt}</p>
    </Container>
  );
};


export const Pricing = ({ data, render = renderPricingCard }) => {

  // sort data by "block.order" so that we can ensure the first item is always the heading
  const [pricesHeading, ...restPricing] = data.sort((a, b) =>
    a.block.order > b.block.order ? 1 : -1
  );
  return (
    <>
      <PricesHeading block={pricesHeading.block} />
      <Container className={styles.prices}>
        <Row className='fluid'>
          {/*
          the restPricing array will always have 3 prices in it
          -- use sort to target the middle price as the featured price
          -- then immediately iterate over that sorted array and render each PricingCard
          */}
          {restPricing.sort((a, b) => (a.title > b.title ? -1 : 1)).map(render)}
        </Row>
      </Container>
    </>
  );
};

export const PricingCard = ({ pricing, isFeatured }) => {
  return (
    <>
      <div
        className={styles.price_card}
        style={{
          width: isFeatured ? "1200px" : "100%",
          border: isFeatured ? "2px solid var(--secondary)" : "none",
        }}
      >
        <div className={styles.pricepoint}>
          <p>{pricing.block.lead}</p>
          <h2>${pricing.block.title}</h2>
          <small>{pricing.block.excerpt}</small>
          <br />
          <p className={styles.excerpt}>{pricing.block.content}</p>
        </div>

        <MarkdownJSX
          markdown={pricing.block.bullets}
          type='pricing'
          highlight={isFeatured}
        />
        <div>
          <Link
            className={`button primary ${isFeatured ? "" : "outline"}`}
            href={pricing.block.links.href}
          >
            {pricing.block.links.title}
          </Link>
        </div>
      </div>
    </>
  );
};


function renderPricingCard(pricing, i) {
  return (
    <PricingCard
      key={`${pricing.id}-${i}`}
      pricing={pricing}
      // price at index: 1 is the featured price value.
      isFeatured={i === 1} // used to highlight the featured pricepoint
    />
  );
}

Most of the logic here is handled by the Pricing component, where we sort the data accordingly by block.order and render the PricesHeading and each of the PricingCard components.

☝️You might've noticed that we sort our prices by title before we render each PricingCard. This is because we use the title field in our Airtable base to populate the actual price value. So essentially when we sort by title we're actually sorting by price point.

Time for the final component, this one is simple once again:

// pages/landing.js

import {
  BenefitsCards,
  BrandList,
  FeaturedBenefit,
  FooterCta,
  Header,
  Hero,
  Pricing,
  RiskCta,
  Testimonial,
} from "../components/landing";

export default function Landing({ page }) {
  const { seo, page: rows } = page;
  const [
    { landingHero },
    { landingBrandList },
    { landingBenefitsIntro },
    { landingBenefits },
    { landingFeaturedTestimonial },
    { landingFeaturedBenefit1 },
    { landingFeaturedBenefit2 },
    { landingFeaturedBenefit3 },
    { landingCtaRisk },
    { landingPricing },
    { landingCtaUrgency },
  ] = sortRows(rows);

  const [featuredTestimonial] = landingFeaturedTestimonial;

 return (
    <>
      <SEO seo={seo} />
      <div className={styles.pageWrapper}>
        <Header brandName={seo?.title} />
        <main className={styles.main}>
                {/* truncated for brevity */}

            <Section className='primary-lighter'>
              <Container style={{ margin: "4em auto" }}>
                <FooterCta block={landingCtaUrgency[0].block} />
              </Container>
            </Section>

        </main>

        {/* truncated for brevity */}
      </div>
    </>
  ); 

}

And that's it for the last component...

Lastly, here's the completed markup for the pages/landing.js file, take a look at this if you need to compare your work or get stuck.

// pages/landing.js

import { SEO } from "../components/SEO";
import { Container, Section, Row } from "../components/Containers";
import {
  BrandList,
  BenefitsCards,
  FeaturedBenefit,
  Header,
  Hero,
  Pricing,
  RiskCta,
  Testimonial,
  FooterCta,
} from "../components/landing";

import { PageBuild, sortRows } from "../utils/data-helpers";
import styles from "../styles/Landing.module.css";

export default function Landing({ page = {} }) {
  const { seo, page: rows } = page;

  const [
    { landingHero },
    { landingBrandList },
    { landingBenefitsIntro },
    { landingBenefits },
    { landingFeaturedTestimonial },
    { landingFeaturedBenefit1 },
    { landingFeaturedBenefit2 },
    { landingFeaturedBenefit3 },
    { landingCtaRisk },
    { landingPricing },
    { landingCtaUrgency },
  ] = sortRows(rows);

  const [featuredTestimonial] = landingFeaturedTestimonial;

  return (
    <div className={styles.pageWrapper}>
      <SEO seo={seo} />
      <Header brandName={seo?.title} />
      <main className={styles.main}>
        <Section style={{ padding: "2em", textAlign: "center" }}>
          <Hero block={landingHero[0]?.block} />
          <Container>{<BrandList data={landingBrandList} />}</Container>
        </Section>
        <Section className='secondary-light'>
          <BenefitsCards
            headingBlock={landingBenefitsIntro[0].block}
            // sort by block order ASC
            data={landingBenefits.sort((a, b) =>
              a.block.order > b.block.order ? 1 : -1
            )}
          />
          <Testimonial block={featuredTestimonial.block} />
        </Section>
        <Section>
          <Container>
            <FeaturedBenefit
              block={landingFeaturedBenefit1[0].block}
              alternate={landingFeaturedBenefit1[0]["filter"].includes(
                "reverse"
              )}
            />
          </Container>
          <div style={{ width: "100%", background: "var(--primary-light)" }}>
            <Container>
              <FeaturedBenefit
                block={landingFeaturedBenefit2[0].block}
                alternate={landingFeaturedBenefit2[0]["filter"].includes(
                  "reverse"
                )}
              />
            </Container>
          </div>
          <Container>
            <FeaturedBenefit
              block={landingFeaturedBenefit3[0].block}
              alternate={landingFeaturedBenefit3[0]["filter"].includes(
                "reverse"
              )}
            />
          </Container>
          <div style={{ width: "100%", background: "var(--secondary-light)" }}>
            {/* <Container> */}
            <RiskCta block={landingCtaRisk[0].block} />
            {/* </Container> */}
          </div>
        </Section>
        <Section>
          <Container>
            <Pricing data={landingPricing} />
          </Container>
        </Section>
        <Section className='primary-lighter'>
          <Container style={{ margin: "4em auto" }}>
            <FooterCta block={landingCtaUrgency[0].block} />
          </Container>
        </Section>
      </main>
      <footer className={styles.footer}>
        {" "}
        &copy;
        <span>Uptime Sentry</span> {new Date().getFullYear()}
      </footer>
    </div>
  );
}

export async function getStaticProps() {
  const { getPage } = await import("../lib/pg");

  const response = await getPage("landing");
  const page = PageBuild(response?.rows);

  return {
    props: {
      page,
    },
  };
}

And here's what your completed landing page should resemble:

Summary

With that completed we've come to end of this series. For those of you who followed along the entire way, I cannot express by gratitude enough! Thank you for taking the time to power through this, and congratulations to you for sticking with it and learning something new!

You now have a fully functional CMS that you can scale for just about any use-case. You can couple that with any frontend technology or framework that you prefer, atlhough my suggestion would be to opt for something that allows you to statically generate your pages.

Next Steps

With that completed, we've come to the end of this series. For those of you who followed along the entire way, I cannot express my gratitude enough! Thank you for taking the time to power through this, and congratulations to you for sticking with it and learning something new!

You now have a fully functional CMS that you can scale for just about any use case. You can couple that with any frontend technology or framework that you prefer, although my suggestion would be to opt for something that allows you to statically generate your pages.

All of the content you need is already included in the testimonials table, so give yourself a challenge and see if you can create this on your own.

While you're trying new things, Next.js recently came out with v11.0.0 which introduced several image support enhancements such as blurred placeholders. If you'd like I suggest upgrading the project to use v.11.0.0. Try to challenge yourself and add blurred image placeholders to your project.

Finally, we've only used CSS Modules for styling our components in this entire project, I would highly recommend trying some other framework or methodology for your own projects. I personally prefer Chakra-UI whenever possible. The team at Chakra does a great job of creating really useful defaults for components with very thoughtful variants. I'll be doing a few articles on Chakra in the coming weeks, so be sure to follow if you're interested in that.

If you have any questions, issues, or just want to reach out you can feel free to hit me up on Twitter: @soham_asmi or feel free to leave me a comment here and I'll do my best to help in any way I can.

Thank you once again, and Happy Coding!

10 VSCode Extensions I Can't Live Without

gshah2020 — Wed, 07 Jul 2021 13:30:44 +0000

1. Advanced New File

Quickly create new files directly from the command palette or use the keyboard shortcut.

Usage:

cmd + option/alt + n

author: Dominik Kundel

source: Advanced New File - Visual Studio Marketplace

2. Duplicate Action

It’s unbelievable that vscode doesn’t have a native file duplication option. But with this extension you can duplicate files directly from your VSCode sidebar.

Usage:

Open any file and Press F1, then select Duplicate File

-or-

Right-click on any file in the sidebar and select Duplicate File

author: mrmlnc

source: Duplicate action - Visual Studio Marketplace

3. File Peek

Quickly view contents of linked files and view them in-line in the current document or jump directly to the file and open it in a new editor.

Usage:

Peek: Loads files inline cmd + shift + F2

Go To: Jump directly to file in new editor F12

Hover: Show the definition while hovering cmd + hover

author: abierbaum

source: File Peek - Visual Studio Marketplace

4. Gist

Create and Edit gists directly from your VSCode editor. Pull content directly from Gists and create new files in your current code base.

Usage:

Use the command palette shift + cmd + p and one of the provided actions:

GIST: Create New Gist

GIST: Open Gist
GIST: Open Favorite Gist

GIST: Delete Gist
GIST: Delete File
GIST: Add File
GIST: Open Gist In Browser
GIST: Insert Text From Gist File

author: Ken Howard

source: Gist - Visual Studio Marketplace

5. Git File History

Time travel any git version controlled file quickly and intuitively.

Usage:

Select Git File History fromt he command palette.

author: Rodrigo Pombo

source: Git File History - Visual Studio Marketplace

6. Surround

Easilly wrap your code block with wrapper snippets like "try/catch".

Usage:

Select the snippet you want to wrap inside a code block,
then right-click or press cmd + shift + t
then select the type of wrapper you want to use from the dropdown

author: Mehmet Yatkı

source: Surround - Visual Studio Marketplace

7. Search with Cursor

Search selected text with Google.

Usage:

Highlight the text you need to search for
then press shift + option + s

author: hasefumi23

source: Search with cursor - Visual Studio Marketplace

8. Template String Converter

Converts quotes to backticks when a $ and { are entered within quotes in JavaScript and TypeScript files.

Usage:

Works automatically, just enter ${} into any string and the extension will convert the string into a template literal expression.

author: meganrogge

source: Template String Converter - Visual Studio Marketplace

9. Turbo Console Log

Quickly write meaningful console.log statements to debug your code base easier. Also allows to globally comment out logs inserted by the extension on a per file basis. You can also customize the boilerplate template used to meet your own needs.

Usage:

Select the references you want logged out then press crtl + option + L

author: ChakrounAnas

source: Turbo Console Log - Visual Studio Marketplace

*NOTE: * there seem to be several versions of this extension in the VSCode marketplace and I have not tried any of the others, so make sure you the the right version mentioned above.

10. Postcode

REST client that allows you to test your HTTP requests right from VSCode. There are several others (thunder client and RESTclient), but I find this to be the simplest, no bells/no frills.

Usage:

Select "Postcode" from the command palette.

author: https://marketplace.visualstudio.com/publishers/rohinivsenthil

source: Postcode - Visual Studio Marketplace

Hey everyone, I'm Gaurang, a full-stack developer that is constantly learning and building in public. I love that I was able to change my career at such a late stage in life all by learning online with so many different resources. I generate content to reinforce what I'm learning and to help others like me in the future.

If you enjoyed my content, please feel free to connect with me wherever you spend your time online.

Build a Splash Page with Next.js, Airtable and SyncInc

gshah2020 — Mon, 05 Jul 2021 14:36:49 +0000

In the previous article of this series, we built a splash page using the Airtable.js package to query our data from an Airtable base. We also took a deep dive into what Airtable actually is and how you can use it with Next.js to help generate static pages directly from your Airtable data.

NOTE: The previous article is not a pre-requisite for following along in this article, but if you’ve never worked with Airtable before I highly recommend starting there to get a better idea of how we’re using Airtable.

In this article, we’ll take a step-by-step look at how to set up SyncInc and use it to synchronize your Airtable base with a fully provisioned cloud-based Postgres instance. We’ll still be working with the same Airtable base, so in the end, you will once again, end up with the same splash page. In contrast, you’ll be able to see how SyncInc helps us simplify the logic required to achieve the same solution using the raw power of SQL to query your data from Airtable

If you followed along with the first article in this series, then you already know how cumbersome it can be to query Airtable directly. Even when using the Airtable.js package, there’s a ton of boilerplate that is required just to get our data from Airtable. Using SyncInc we not only get a more scalable solution but also a more efficient and performant way to get data from Airtable to the front-end of our applications.

What is SyncInc?

SyncInc is a production-grade synchronization service used to create and synchronize a “follower” Postgres database with various third-party APIs.

Why SyncInc

Generous Free-tier
Fully-provisioned cloud Postgres database hosted on AWS or co-located with an existing database
Production-grade integrations like Shopify, Stripe, Twilio and of course Airtable.
Automatic schema generation
Single source of truth for multiple data sources
All the advantages of postgres.

Pre-requisites

Basic understanding of Javascript(ES6) and React.
General understanding of relational databases, SQL statements and joins.
System Requirements
- Node.js 10.13 or later
- Either macOS, Windows (including WSL), or Linux

Resources

Airtable Base - This is the Airtable database you’ll be working from.

Starter Branch - You can use this branch to clone the starter for this project and follow along.

Final Branch - Use this branch to compare your work if you run into any issues.

Codesandbox Starter - You can also follow along using this CodeSandbox starter project.

Preview - This is a working demo of the end product of this article.

Before we get started, you’ll need

an Airtable account
you’ll need to clone the Airtable base provided above in the Resources section. You’ll also need your Airtable API key handy, which can be found here.

☝️ Once again, you can refer to the Airtable Setup section of the last article.

SyncInc Setup

If this is your first time signing up then click the button labeled "Let's go" to continue, otherwise, you'll be redirected to your dashboard.

For the next step, you'll need your Airtable API key from here.

☝️ If you haven't set up your Airtable account or haven't cloned the Airtable base used for this project - please complete the setup using the directions provided in the Airtable Setup section of the first article.

If you've successfully cloned the provided Airtable base, should see a base named "site" listed in your available bases.

Make sure that you toggle "Sync all tables in this base" on and select "New Sync Inc database".

You'll be given a quick on-boarding questionnaire select the option that fits best for you or just click "Skip" to continue.

After a few moments, your new synchronized database will be fully provisioned. Once the setup completes you'll be provided with your credentials.

Project Setup

Once you have access to your SyncInc credentials, you can turn your attention towards setting up the project locally.

Clone the starter branch, by running the following command.

git clone -b post2-starter https://github.com/gaurangrshah/next-airtable-splash.git

Navigate to the project directory.

cd next-airtable-splash

Install project dependencies.

yarn

Once your packages have been installed. Go ahead and spin up your development server and ensure that the application is running properly.

yarn dev

If all goes well you should see a page that looks similar to the one below.

Let's take a moment to familiarize yourself with this starter template. For the most part, this is a typical boilerplate Next.js application.

.
├── README.md
├── components
│   ├── Containers.js
│   ├── Cta.js
│   ├── Hero.js
│   ├── List.js
│   └── Splash.js
├── lib
├── next.config.js
├── package.json
├── pages
│   ├── _app.js
│   ├── api
│   │   └── hello.js
│   └── index.js
├── public
│   ├── favicon.ico
│   └── vercel.svg
├── styles
│   ├── Containers.module.css
│   ├── Cta.module.css
│   ├── Hero.module.css
│   ├── Home.module.css
│   ├── List.module.css
│   └── globals.css
├── utils
│   └── data-helpers.js
└── yarn.lock

You'll find that the starter also includes all of the styles and each of the components you'll need for this project including a few helper functions that will make handling the data a bit simpler.

Connect to your Sync Inc Database

Next up we'll look at how to get our data into our application from Airtable. We'll start by using the pg package to connect with and query from our synchronized Postgres database that we generated with Sync Inc.

In the last article, we used the Airtable.js package to help query our Airtable data, this time around we'll use the pg package to help do the same with our Postgres database. You should see a stark contrast in both the amount of boilerplate you no longer need and how we can simply all of the logic we implemented previously into a single SQL statement which will return all of the data we need.

Let's start by adding pg as a dependency by running the following command:

yarn add pg

pg allows us to interact with postgres databases from node.js environments using the full power of raw SQL queries. Alternatively, pg is often known as node-postgres

📒 More about pg

Next, you'll need to set up your environment variables to configure your SyncInc database.

From your SyncInc dashboard click the "Connect" button.

You'll need to fill in the corresponding values from the credentials tab of the SyncInc dashboard.

Create a new file called env.local at the root of your project and copy the variables below:

# .env.local

DB_USER=
DB_HOST=
DB_NAME=
DB_PW=
DB_PORT=

— see .env.sample file included with the starter for this project.

— see more on environment variables in Next.js

With your environment variables defined, you can now set up your database client. Create a new file under the /lib directory named pg.js.

// lib/pg.js

const { Client } = require('pg');


// create client instance
const client = new Client({
    user: process.env['DB_USER'],
    host: process.env['DB_HOST'],
    database: process.env['DB_NAME'],
    password: process.env['DB_PW'],
    port: process.env['DB_PORT']
  });


module.exports = {
  client
}

Query Your Synced Database

Once you've instantiated the database client, the next step is to create the SQL query you'll need to grab all of your Airtable data that your application needs all at once.

☝️ Be forewarned, the query example below may seem a bit verbose, but that is really because we're not only querying for all of our data at once, but we're also explicitly renaming all of our fields at the same time.

SELECT /* Select and rename each field accordingly */
    p.id AS page_id,
    p.title AS page_title,
    p.path AS page_path,
    p.order_ AS page_order,
    p.sectionid As page_sections_id,
    p.seoid AS page_seo_id,
    s.id AS section_id,
    s.title AS section_title,
    s.order_ AS section_order,
    s.type AS section_type,
    s.filter AS section_filter,
    s.blockid AS section_block_id,
    s.pageid AS section_page_id,
    b.id AS block_id,
    b.title AS block_title,
    b.lead AS block_lead,
    b.excerpt AS block_excerpt,
    b.content AS block_content,
    b.mediaid AS block_media_id,
    b.sectionid AS block_section_id,
    m.id AS media_id,
    m.title AS media_title,
    m.url AS media_url,
    m.alt AS media_alt,
    m.blockid AS media_block_id,
    m.seoid AS media_seo_id,
    seo.id AS seo_id,
    seo.title AS seo_title,
    seo.description AS seo_description,
    seo.keywords AS seo_keywords,
    seo.sitename AS seo_sitename,
    seo.url AS seo_url,
    seo.mediaid AS seo_media_id,
    seo.pageid AS seo_page_id
FROM
    pages AS p /* target table */

        /* match data from different tables  data by id */
    LEFT JOIN seo ON seo.id = ANY (p.seoid) 
    LEFT JOIN sections AS s ON s.id = ANY (p.sectionid) 
    LEFT JOIN blocks AS b ON b.id = ANY (s.blockid)
    LEFT JOIN media AS m ON m.id = ANY (b.mediaid)
    ORDER BY p.id ASC, s.order_ ASC;

NOTE: You could just as easily rename the fields in your Airtable base, and reduce the bulk of the query logic. But it's important to understand how to coerce data into the shape required by your application since you may not always have control over how the data is provided.

Table Plus Setup

At this point it may be a good idea to test this query by running it against your database from any database admin software. You can find many free/freemium tools (i.e., SequelPro, Postico, DBeaver), although we'll be using TablePlus, because it's extremely simple to use with a great UI.

TablePlus is an extremely powerful utility that you can use with almost any type of database, it's definitely a great tool to have in your repertoire.

But for our purposes we'll only be using it to test the query we wrote above against our database to ensure we're getting back the correct data.

Start by downloading TablePlus.

Once your download completes double click on the file and install the application.

The installer should guide you through the process with instructions relevant to your platform.

Once the installation completes open TablePlus and click the "Create a new connection" link at the bottom of the window.

Next click the "Import from URL" button.

Then inside the dialog enter your postgres connection URL and click the "Import" button

☝️NOTE: You can find the connection URL in your SyncInc dashboard as shown below:

Next you can name your new connection and then click the "TEST" button to test your connection. If successful you should see all of the fields from your connection configuration turn green.

Once your connection test passes, you can feel free to click the "Connect" button, this will open of the default application view.

You should see all of your tables from your Airtable base listed in the left sidebar. You can click on any of them and browse through your data.

But for now we simply want to run a quick query against our data. To do that click the "Queries" tab at the top fo the left sidebar.

Then right-click to create a new folder called "syncinc".

Then right -click on the new "syncinc" folder and create a new file. The new file will open in its own window.

Rename the file, and then paste in the SQL query we constructed.

You can the close the file and double-click on it from the sidebar. This will open the query in the editor.

Now you can simply click the button labeled "Run Current". You'll see the data returned almost instantly as shown above.

NOTE: Because of how a LEFT JOIN works each row also has duplicated data regarding the page that it is related to. Since there is only a single page record in your Airtable base, the data is identical for each instance. This is the expected behavior and we'll deal with transforming this data further to fit our application's needs during the build step.

☝️ More about Postgres Left Joins

ALSO NOTE: If you look at the data closely you'll notice that your query returns one row for each block in your Airtable base.

Now that you know the query logic works let's take the query and create a reference to it so we can use it within our application.

Let's create a new file called queries.js in lib/queries.jsand construct our query in this file.

// lib/queries.js

export const SECTIONS_QUERY = `SELECT
      p.id AS page_id,
      p.title AS page_title,
      p.path AS page_path,
      p.order_ AS page_order,
      p.sectionid As page_sections_id,
      p.seoid AS page_seo_id,
      s.id AS section_id,
      s.title AS section_title,
      s.order_ AS section_order,
      s.type AS section_type,
      s.filter AS section_filter,
      s.blockid AS section_block_id,
      s.pageid AS section_page_id,
      b.id AS block_id,
      b.title AS block_title,
      b.lead AS block_lead,
      b.excerpt AS block_excerpt,
      b.content AS block_content,
      b.mediaid AS block_media_id,
      b.sectionid AS block_section_id,
      m.id AS media_id,
      m.title AS media_title,
      m.url AS media_url,
      m.alt AS media_alt,
      m.blockid AS media_block_id,
      m.seoid AS media_seo_id,
      seo.id AS seo_id,
      seo.title AS seo_title,
      seo.description AS seo_description,
      seo.keywords AS seo_keywords,
      seo.sitename AS seo_sitename,
      seo.url AS seo_url,
      seo.mediaid AS seo_media_id,
      seo.pageid AS seo_page_id
    FROM
      pages AS p
      LEFT JOIN seo ON seo.id = ANY (p.seoid)
      LEFT JOIN sections AS s ON s.id = ANY (p.sectionid)
      LEFT JOIN blocks AS b ON b.id = ANY (s.blockid)
      LEFT JOIN media AS m ON m.id = ANY (b.mediaid)
      ORDER BY p.id ASC, s.order_ ASC
    `;

You can then import the query into the same file that you defined the database client in /lib/pg.js and create a function called getSections() that you can use to query against your Postgres database directly from your application.

// lib/pg.js

import { SECTIONS_QUERY } from "./queries";

/*

truncated...

*/

async function getSections() {
  try {
    await client.connect(); // connect to db

    // query database for sections and all related data.
    const res = await client.query(SECTIONS_QUERY);

    // handle success
    // console.log("res--", res);
    await client.end(); // close connection to db

    return res;
  } catch (err) {
    // handle errors
    console.error(err);
  }
}

module.exports = {
  client,
  getSections,
  SECTIONS_QUERY,
};

That's it. That's all the logic we need to query all of our data from Airtable. You might recall from the first article, that it took a lot more work to query the same data using Airtable.js. This is the power of Postgres on full display with the help of SyncInc. As you can see we've significantly decreased the development time. And because we're dealing with Postgres we also have the full benefit of it's plugin eco-system and third-party utilities (like TablePlus).

Next, let's put our logic to work in our application by ensuring that getSections() is called asynchronously at build time using getStaticProps().

☝️ You might recall from the last article, that getStaticProps() will get called once at build-time for each top-level page in your application. So any logic we have within it will be run once during the build process. That data is then cached and used to generate the content for each of the static pages in your application. In our case, we just have a single page.

// pages/index.js

import Head from "next/head";

import { removeNullValues } from "../utils/data-helpers";
import styles from "../styles/Home.module.css";

export default function Home({rows}) {
  return (
    <div className={styles.container}>
      <Head>
        <title>Create Next App</title>
        <link rel='icon' href='/favicon.ico' />
      </Head>

      <main className={styles.main}>
        <h1 className={styles.title}>
          Welcome to <a href='https://nextjs.org'>Next.js!</a>
        </h1>
                <div style={{ maxWidth: "80%", margin: "0 auto" }}>
          {JSON.stringify(rows, null, 2)}
        </div>
      </main>
    </div>
  );
}

export async function getStaticProps() {

    // asynchronously import getSections to avoid any client side evaluation.
  const { getSections } = await import("../lib/pg");

  const response = await getSections();

    // removes any fields with empty or undefined values to avoid any serialization errors
  const rows = removeNullValues(response?.rows); 

  return {
    props: {
      rows, // return data as props.
    },
  };
}

With this in place, you should now be able to see something that matches the image below where you're simply dumping all of the data to the screen to make sure you're able to view the data on the front-end of the application.

You probably noticed that we used a function called removeNullValues() in getStaticProps(). removeNullValues() is a helper function that was included in the starter. It actually uses another one of our helper functions isEmpty() to find and any empty, null, or undefined values from our data.

// utils/data-helpers.js

export function removeNullValues(arr) {
  return arr?.map((obj) => {
    Object.keys(obj)?.forEach((key) => {
      if (isEmpty(obj[key])) delete obj[key];
    });
    return obj;
  });
}

export function isEmpty(value) {
  return (
    value === undefined ||
    value === null ||
    (typeof value === "object" && Object.keys(value).length === 0) ||
    (typeof value === "string" && value.trim().length === 0)
  );
}

export function groupBy(arr, key) {
  return arr.reduce(function(rv, x) {
    (.rv[x[key]] = rv[x[key]] || []).push(x);
    return rv;
  }, {});
};

export function Section(data) {
  return {
    id: data?.section_id || "",
    title: data?.section_title || "",
    order: data?.section_order || "",
    type: data?.section_type || "",
    filter: data?.section_filter || "",
    block: {
      id: data?.block_id || "",
      lead: data?.block_lead || "",
      title: data?.block_title || "",
      excerpt: data?.block_excerpt || "",
      content: data?.block_content || "",
      media: {
        id: data?.media_id || "",
        title: data?.media_title || "",
        alt: data?.media_alt || "",
        url: data?.media_url || "",
      },
    },
  };
}

Build the site

Now that you have your data and you're able to view it on the front-end, you can now use it to render the components that were provided with your project starter.

SEO and Metadata

But before we render any of the components, you'll see that we are able to grab the SEO metadata we need for our page from our Airtable data. We use a reference to the first row from our data in order to grab all of the fields we need.

☝️ Recall: each row has this same data available to it, we could've used any of the rows from our data and we'd get the same data because we are only rendering a single page.

// pages/index.js

import Head from "next/head";

import { Splash } from "../components/Splash";
import { removeNullValues } from "../utils/data-helpers";

import styles from "../styles/Home.module.css";

export default function Home({ rows }) {
  return (
    <div className={styles.pageWrapper}>
      <Head>
        <title>{rows[0]?.seo_title}</title>
        <meta name='viewport' content='initial-scale=1.0, width=device-width' />
        <meta name='description' content={rows[0]?.seo_description} />
        <meta property='og:title' content={rows[0]?.seo_title} />
        <meta property='og:site_name' content={rows[0]?.seo_sitename} />
        <meta property='og:url' content={rows[0]?.seo_url} />
        <meta property='og:description' content={rows[0]?.seo_description} />
        <meta property='og:image' content={rows[0]?.url} />
        <link rel='icon' href='/favicon.ico' />
        <link rel='cannonical' href={rows[0]?.url} />
      </Head>

      <main className={styles.main}>
        <Splash data={rows} />
      </main>
    </div>
  );
}

export async function getStaticProps() {
  const { getSections } = await import("../lib/pg");

  const response = await getSections();
  const rows = removeNullValues(response?.rows);

  return {
    props: {
      rows,
    },
  };
}

Then, let's take a closer look at the Splash component that is responsible for rendering all of that data. You'll notice that we do some data wrangling here to create a new Section from the data using a Section() factory function that takes in our raw data and returns the data shaped exactly as our application expects.

You can then render the Hero section separately by destructuring it off of the new array of sections. And then you can group the remaining sections by their type so we can render them with the appropriate component for each, based on those types.

// components/Splash.js

import { Container, Wrapper, Row } from "./Containers";
import { Hero } from "./Hero";
import { List } from "./List";
import { Cta } from "./Cta";
import { groupBy, Section } from "../utils/data-helpers";

// components to be used for rendering Airtable data
const components = {
  list: List,
  cta: Cta,
};

export const Splash = ({ data }) => {

  if (!Array.isArray(data)) return null;

  // transform Airatble data
  const sections = data.map((section) => {
        return new Section(section); // create section from queried data
  });
  const [hero, ...rest] = sections;
  const restSections = rest?.length ? groupBy(rest, "type") : rest;

  return (
    <Wrapper>
      <Container>
        {hero && (
          <Hero
            key={hero?.block?.id}
            data={hero?.block}
            filter={hero?.filter}
          />
        )}
        <Row>
          {Object.keys(restSections)?.map((key, i) => {
            const Component = components[key]; // component to use for rendering
            const section = restSections[key]; // section to be rendered
            return (
              <Component
                key={`section-${section[i]?.block?.id}`}
                data={section}
              />
            );
          })}
        </Row>
      </Container>
    </Wrapper>
  );
};

With this in place, your template is complete, and all of our components for the Splash page will render according to their data. We'll step through each one in a bit of detail, but this should be nothing new to anyone who's worked with React before.

The Hero component simply renders the headline and some additional copy as well as a large hero image.

// components/Hero.js

import styles from "../styles/Hero.module.css";
import Image from "next/image";

export const Hero = ({ data }) => {
  return (
    <div className={styles.hero}>
      <div className={styles.heroContent}>
        <p className={styles.lead}>{data?.lead}</p>
        <h1 className={styles.heading}>{data?.title}</h1>
        <p className={styles.excerpt}>{data?.excerpt}</p>
      </div>
      {data?.media && (
        <div className={styles.heroImage}>
          <Image
            layout='intrinsic'
            src={data?.media?.url[0]}
            alt={data?.media?.alt}
            objectFit='fill'
            width={600}
            height={600}
          />
        </div>
      )}
    </div>
  );
};

The List component renders our features & benefits and uses a filter we defined in Airtable to render each with its corresponding icon.

// components/Lists.js

import Image from "next/image";
import styles from "../styles/List.module.css";

export const List = ({ data }) => {
  return (
    <ul className={styles.list}>
      {data?.map((section) => {
        const { block } = section;
        return (
          <ListItem
            key={block?.id}
            className={styles.listItem}
            img={block?.media}
            data={data}
            style={{ order: block }}
          >
            {block?.title}
          </ListItem>
        );
      })}
    </ul>
  );
};

export const ListItem = ({ img, data, children }) => {
  return (
    <li className={styles.listItem}>
      {data[0].filter[0] === "withIcons" && (
        <span className={styles.icon}>
          <Image
            layout='intrinsic'
            src={img?.url[0]}
            alt={img?.alt}
            width='28px'
            height='28px'
          />
        </span>
      )}
      {children}
    </li>
  );
};

Lastly, we have the Cta component that renders an email sign-up form. Once again we use the filter field to only include the form when the withForm value is present.

// components/cta.js

import styles from "../styles/Cta.module.css";

export const Cta = ({ data }) => {
  const handleSubmit = (e) => {
    e.preventDefault();
    const input = e.target.querySelector("input");
    console.log(input.value);
  };

  return (
    <div className={styles.cta}>
      {data?.map(({ block }, i) => {
        return (
          <div key={block?.id}>
            <h2>{block?.title}</h2>
            <p>{block?.excerpt}</p>
            {data[i]?.filter.includes("withForm") && (
              <form onSubmit={handleSubmit}>
                <div className={styles.inputGroup}>
                  <input
                    type='email'
                    placeholder='you@youremail.com'
                    required
                    className={styles.input}
                  />
                  <div className={styles.inputRight}>
                    <button type='submit' className={styles.submit}>
                      Sign up now
                    </button>
                  </div>
                </div>
              </form>
            )}
          </div>
        );
      })}
    </div>
  );
};

Summary

That's it, you've successfully created a splash page using data from your Airtable base, but by querying it from a synchronized Postgres database provided by SyncInc.

If all goes well, you should see something similar to the CodeSandbox example:CodeSandbox Preview

If you followed along with both articles so far then the differences between each approach should be pretty evident. But in case it's not let's take a look at some of the pros and cons of using SyncInc to query your Postgres data.

Pros

Less overhead to query to data from Airtable.
More powerful query syntax with raw SQL.
Much more flexibility - use any O.R.M. that works with Postgres.
Faster, more efficient and cleaner codebase.
Take advantage of all available Postgres features.

Cons

I can only think of one cons here and it's not much of a deal-breaker in my opinion. It has to do with the way follower databases work in general. Follower databases maintain uni-directional sync with a leader database. With Airtable that means our SyncInc database will always stay in sync with Airtable, but if we add data via Postgres, then Airtable will have no record of that change. This is why in general all changes are usually made to the leader database (Airtable) directly and updates are then synced using SyncInc to your follower Postgres database.

Although the great people over at SyncInc have also anticipated this and provided a way of writing back to your Postgres database using a Proxy. So you can still use SQL to implement any CRUD functionality that your application will need. This allows you to write back to both your Airtable base and your Postgres database instantly using Airtable.js or even the built-in fetch API.

For more on SyncInc Proxy writes

That's it for this article, I hope you'll check out the third and final installment in the Airtable as a CMS series, where we'll go one step further and take a look at how you can "Build a Landing Page with Airtable as a CMS".

And be sure to follow me on twitter: @soham_asmi to stay up to date with my latest projects and posts. Also, please feel free to reach out to me with any questions you may have along the way.

Until next the next one... 👋

If you enjoyed my content, please feel free to connect with me wherever you spend your time online.

Build a Splash Page with Next.js using Airtable as a CMS.

gshah2020 — Mon, 14 Jun 2021 14:06:49 +0000

Introduction

Let's build a fully optimized landing page using Airtable and Next.js. Over the course of this 3-part series, you'll work your way up to building a highly scalable landing page with an easy-to-use custom Airtable CMS.

In this first post, we'll begin, with a general overview of Airtable and Next.js and why the combination makes an ideal solution for several real-world applications. You'll also learn how to configure an Airtable "base" and integrate it with Next.js using static site generation (SSG).

In the rest of the series, you'll see how you can simplify the solution and scale using Sync Inc. Which provides a synchronized cloud-based Postgres instance so you can run raw SQL queries against your Airtable data.

What We're Building

In this first post, we'll build a simple yet versatile Splash page. Splash pages used to be more common in the past, but we still see remnants of them in modern applications. Splash pages generally are full-screen pages that are typically used for a single purpose, the most common example would be a 404 page.

The Brief

In our case, we're building a splash page for an up-and-coming Saas startup that provides uptime monitoring services. Our goal is to create an attractive "call-to-action" splash page to act as a placeholder while the full site and app are being built. This will help ensure the company can capture any early interest in their product and creates a list of followers who are enthusiastic about their upcoming launch.

By the end, you'll have a working, fully customizable splash page...

built using Airtable as a CMS with markdown support.
statically generated by Next.js
with built-in SEO support and image optimization.

Later in the series, you'll learn how you can:

simplify the integration with Sync Inc.
scale using a fully provisioned cloud Postgres database.
leverage the power and simplicity of raw SQL queries.

Visit Splash Page Demo

What is Airtable?

Airtable is an online platform for managing and sharing relational data in an easy-to-use collaborative workspace. On the surface, Airtable looks like a fun spreadsheet but functions like a robust relational database and provides various tools, integrations, and automations that make it a very effective solution for most use-cases.

Why Airtable?

Generous Free Tier
Powerful Automations

What is Next.js?

Next.js is a highly versatile, production-grade React framework. It provides thoughtful optimizations that just work such as a built-in CDN, server-less functions, and link prefetching. To take it one step further Next.js allows the developer to choose between static and server rendering on a per-page page basis.

Why Next.js?

Super-fast performant websites and applications
Optimized for production from the start
Developer's choice: Static or Server Rendering
Typescript and CSS Support

Prerequisites

Basic understanding of Javascript(ES6) and React.
General understanding of relational databases, SQL statements and joins.
System Requirements
- Node.js 10.13 or later
- Either macOS, Windows (including WSL), or Linux

Resources

Airtable Base - This is the Airtable database you'll be working from.
Starter Repo - You can use this repo to clone our starter and follow along.
Finished Branch - Use this repo to compare your work if you run into any issues.
CodeSandbox Starter - You can also follow along using this CodeSandbox starter project.
Project Demo - This is a working demo of the Splash page project from this post.

Airtable Setup

First, let's get an Airtable base set up.

Create an airtable account or sign into your airtable account.
Then click here to Clone the Airtable base you'll be using for this project.

Airtable Credentials

Once you've cloned your base, you'll need both your Airtable API key and base-id to configure your application.

NOTE: The API key should be treated as a secret and should be kept confidential. The base-id is semi-private, but for this project, we'll be treating it as a secret as well.

Generate API key

Let's start by generating your Airtable API key.

Click on your user icon in the top-right-hand corner.

From the drop-down menu select the "Account" option.

Under "Account Overview", click the button labeled "Generate API key".

⚠️ Keep this API key secure, you'll need it when you configure your Next.js application.

Locate Base-Id

You can find your base-id from Airtable's live documentation.

From your base, click the "Help" button on the top-right of your screen.

From the sidebar menu, click the link labeled "API documentation".

You'll find your base-id listed right under the second paragraph in green:

☝️ Keep your base-id secure but available you'll need it to configure your Airtable base with your Next.js application.

Once you have your Airtable credentials, let's move on to setting up your Next.js application.

Structuring Airtable as a CMS

If this is your first time using Airtable then this section will get you up to speed on some of the terminology and concepts you'll need to proceed.

The base you cloned is designed to be very flexible so you can always add fields to customize it once you're semi-familiar with how it functions.

Inside your base, you will find several tables listed at the top of the screen, (pages, sections, blocks, media, and seo ). These tables help us arrange our data logically in a way that resembles a spreadsheet, but functions like a relational database.

As shown above, each table in a base consists of a collection of rows and each row represents an individual record. Records are a collection of fields that hold specific data about the object they represent. More about Airtable structure

Airtable provides you with various field types that can be used to store all kinds of values. For this project we'll only be using a few of the more common field types:

Single line text - used to store small strings of text.
Number - can be configured to hold integers or floating points.
Long text - used for longer text content (i.e., paragraphs).
Single select - select a single option from a predefined list.
Multiple select - select multiple options from a predefined list.
Attachment - used to store files.
Linked Records - used to link a record from one table with another.

NOTE: Even though all of this may seem like a lot, we're actually just scratching the surface here with Airtable. Luckily they have some incredible documentation both for the platform and for the API.

And if you really want to dive deep, I came across this article that covers just about everything you can do with Airtable as a developer.

Tables

We use Airtable's field types in our base to help organize our data, based on the type of values we want to accept for any given field. Let's take a deeper look at each field and the type of data it holds.

pages

field	field type	description
`title`	single line text	represents the title for the current page and can be used to populate nav menus as needed.
`path`	single line text	used to populate the `href` value when linking to a page.
`order`	number	used to control the order in which each page should be displayed (also useful for nav menus).
`sectionId`	linked record	used to link to related sections for each page.
`seoId`	linked record	used to link to SEO metadata for each page.

sections

field	field type	description
`title`	single line text	represents the title for the section (only used for reference purposes).
`order`	number	used to control the order of each section (on a per-page basis).
`type`	single select	used to control which component the application will use to render each section.
`filter`	multiple select	used as a boolean modifier that is useful for conditionally rendering components or layouts.
`blockId`	linked record	used to link to related blocks for each section.
`pageId`	linked record	used to link to the page that will render this section.

blocks

field	field type	description
`title`	single line text	title for each block, used as the heading element's content. (i.e., h1, h2, h3...)
`lead`	single line text	short text block that will be rendered above the heading tag in our application.
`excerpt`	single line text	short text block that will be rendered below the heading tag in our application.
`content`	long text	long from content (i.e., paragraph) that will be rendered as a block of text.
`mediaId`	linked record	used to link to related media for each block.
`sectionId`	linked record	used to link to the section that will render this block.

media

field	field type	description
`title`	single line text	represents the title for each media item (only used for reference purposes).
`url`	attachment	holds a file attachement as an object from which we use the url property.
`alt`	single line text	used to populate the alt tag for each image.
`blockId`	linked record	used to link to the block that will render each media item.
`seoId`	linked record	can be used to reference an image from the `seo` table to be used as the `og:image` for each page.

seo

field	field type	description
`title`	single line text	used to populate the `title` tag for each page.
`description`	single line text	used to populate the `description` tag.
`keywords`	single line text	used to populate the `keywords` tag.
`sitename`	linked record	used to populate the `site_name` tag.
`url`	linked record	used to populate the `site_url` tag.
`pageId`	linked record	used to reference the page that each SEO record belongs to.
`mediaId`	linked record	used to link to related media to be used as the `og:image` for each page.

Relationships

Since one of the pre-requisites of this post was an understanding of relational databases, we won't dive too deep into the following concept of relationships.

In the diagram above you can see each table along with each of its fields and corresponding field types. You can also get a rough idea about how some of the fields are used to link data from different tables together.

At its core Airtable is a relational database. The platform abstracts away a lot of the relational complexity and provides an easy-to-use interface that resembles a spreadsheet instead. Under the hood, relational concepts such as the use of primary and foreign keys are implemented to link records of your Airtable base to one another across your different tables.

Airtable calls these types of fields linked records, but these types of records behave similarly to the way foreign_keys are implemented in relational databases.

If you're not familiar with these relational database terms, I advise taking a quick second to skim through the introduction of this article.
And also more about linked records in Airtable.

In Airtable the first field in each table acts similar to a primary_key. Airtable calls these fields the primary field. In your Airtable base, the first field on each table is the title field which essentially functions as the primary reference to the record it represents.

The contents of each primary field field get indexed by Airtable which means we can search for our records by their title.

☝️ NOTE: It's good practice to make sure the field that is used as the primary_key for each table has a unique value, although Airtable does not enforce this constraint. More about: Airtable primary keys

Naming Convention

We have adopted a simple naming convention (from relational databases) for the naming of each of the foreign_key fields where the field is named as a combination foreign_tablename + "Id".

For example, on the sections table, the pageId field links to a page record so it's aptly named pageId.

This naming convention helps us address a disparity between how the Airtable UI presents data for linked records as a list of titles in our Airtable base versus how the API represents this same data as an array of unique ids.

Airtable API Relationships

Let's dig a bit further at the difference between how data looks in the Airtable UI versus in the Airtable API using a small chunk of the data in your new Airtable base.

The API response snippet shown below for the sectionId field returns an array of ids. Each id in the array represents a linked record.

Airtable response for the sectionId field:
"sectionId": [ "recTiTyzYFdayHJs5", "recm1iacYCQPuIseY", "recnJxlc90m0VYWeu" ]
But in the Airtable UI, these same linked records appear as the sectionId:

Ultimately, this behavior in the API makes sense. Matching and looking up IDs is better than working with ever changing strings.

Relationships can sometimes be tricky to reason about, but we're not doing anything complex here. As long as you have a general understanding of the basics you should feel confident enough to proceed.

Next.js Setup

Starter overview

The starter repo is a boilerplate create-next-app with a single dependency added: airtable.js. All the styles needed for the entire project are included with the starter as CSS modules all located in the /styles directory.

There are a couple of pre-fabricated presentational components and a few helper methods also included with the starter repo. We'll go over each in a bit of detail, but first, let's set up the application.

Clone the starter repo locally.

$ git clone https://github.com/gaurangrshah/next-airtable-splash

Add credentials

Now add your Airtable credentials as environment variables to your local repository. With Next.js you can simply create a file called .env.local at the root of your project. Next.js adds this file to your .gitignore by default and securely injects the variables into your environment at build time. More about: Next.js Environment Variables

# .env.local

AIRTABLE_API_KEY={{YOUR_AIRTABLE_API_KEY_HERE}}
AIRTABLE_BASE_ID={{YOUR_AIRTABLE_BASE_ID_HERE}}

Now that you have your application credentials configured go ahead and start your development server to make sure everything is working for you:

$ yarn dev

Now navigate to http://localhost:3000/ . You should see the welcome message shown below.

And there you have it. Your Next.js application is now running locally and you've got your environment variables configured.

The next thing you'll want to do is configure your Airtable base to work with your Next.js application, but before we get there, let's take a moment to go over the structure of your Airtable base and how it will work as a CMS.

Integrate Airtable

Now, connect your Airtable base to your Next.js app. You already have airtable.js included as a dependency in the package.json file of your Next.js application.

So we can jump right in and begin by instantiating an instance of Airtable in our project.

// lib/airtable.js

const Airtable = require("airtable");
const { getMinifiedRecords, minifyRecord } = require("../utils/airtable");

// airtable queries are based on "views"
export const VIEW = "Grid view";

// instantiate airtable
export const table = new Airtable({
  apiKey: process.env.AIRTABLE_API_KEY,
});

// create reference to airtable base
export const base = table.base(process.env.AIRTABLE_BASE_ID);

Even though airtable.js provides a very easy-to-use wrapper around the Airtable REST API, working with Airtable data on the client-side can be a bit of a clunky process. To make querying the API easier, your starter includes several helper functions. These functions are used to help you interact with the API and make data handling a bit more manageable:

// lib/airtable.js

// Airtable query helpers
export const getPage = async (
  page = "launch",
  table = "pages",
  options = { view: VIEW }
) => {
  // creates a filter allowing your to query your records by searching for matching title values.
  const filterByFormula = `AND(title='${page}')`;

  const records = await base(table)
    .select({ filterByFormula, ...options })
    .all();
  return getMinifiedRecords(records);
};

export const getRecordById = async (table, id) => {
  const record = await base(table).find(id);
  return minifyRecord(record);
};

export const getRelatedRecords = async (table, ids = []) => {
  const records = await ids.map(async (id) => {
    const record = await getRecordById(table, id);
    return record;
  });
  return Promise.all(records);
};

getPage() is a helper function that hard-codes some default logic that you'll need for your queries (i.e, table, page) and provides the ability to pass in any additional options. This allows you to keep your logic extensible. We also make use of the filterByFormula option to target and select the data we need to render the launch page.

getRecordById() is used to query a single record by its id.

getRelatedRecords()is a function that takes in an array of ids. The function calls getRecordById() for each id in the array and returns the results as a single array of records.

Notice the helpers we defined reference two other utility functions getMinifiedRecords() and minifyRecord. These functions do not interact with the Airtable API themselves but are instead used to transform your Airtable records into data that is more manageable on the client-side.

// utils/airtable.js

// maps over the records, calling minifyRecord, giving us required data
export const getMinifiedRecords = (records) => {
  if (!Array.isArray(records)) return minifyRecord(records);
  return records.map((record) => minifyRecord(record));
};

// gets the data we want and puts it into variables we can reference
export const minifyRecord = (record) => {
  return {
    id: record?.id,
    fields: record?.fields,
  };
};

minifyRecord() takes a record from an Airtable response and only returns the data we need for our application. It strips away any helper methods and utility functions that are generally included on the response object by airtable.js.

getMinifiedRecords() takes an array of Airtable response records and calls minifyRecord() for each one before returning the results.

With Airtable instantiated and your helper functions in place, you can turn your attention to using these helpers to fetch your Airtable data and use it to render static a page.

Next.js Data-Fetching

Next.js supports several data fetching strategies out of the box. In this post, we'll be focusing on getStaticProps() which is how we create optimized static pages in Next.js.

Static Site Generation (SSG)

getStaticProps() provides a way for you to query the file system or any external resources during the build process. This means its logic can be executed on the server at build time in your production environment and on each page load in your local development environment.getStaticProps() is an asynchronous function that can be exported from any top-level page component. Next.js will automatically execute this function at build time before generating the static page. More about: getStaticProps()

⚠️ In development, you can always trigger a re-fetch with getStaticProps() by refreshing the page, but in production, you'll have to redeploy the application either manually from your hosting console or with a deploy hook.

☝️ NOTE: Next.js offers two additional data fetching strategies, incremental static regeneration (ISR), and traditional server-side rendering (SSR). Any of these features including static site generation (SSG) can be implemented on a per-page basis. This allows us as the developers to choose which strategy is right for each use case.

For more about each strategy, I highly recommend this article.

Now that you have an idea of what getStaticProps() can do, let's put it to work and use it to query data from your Airtable base.

// pages/index.js

import Head from "next/head";
import styles from "../styles/Home.module.css";

export async function getStaticProps() {
  // asynchronously import neccessary modules so we can avoid any client side compilation
  const { getPage, getRecordById, getRelatedRecords } = await import(
    "../lib/airtable"
  );

  // query inital data from airtable
  const [launch] = await getPage("launch");

  // get related seo metadata
  if (launch?.fields?.seoId?.length) {
    const seo = await getRelatedRecords("seo", launch?.fields?.seoId);

    if (seo[0]?.fields?.mediaId.length) {
      // get related media for seo og:image
      const ogImage = await getRecordById("media", seo[0]?.fields?.mediaId[0]);
      seo[0].fields.ogImage = ogImage;
    }
    launch.seo = seo;
  }

  return {
    props: {
      page: launch?.id ? launch : [],
    },
  };
}

export default function Home({ page }) {
  return (
    <div className={styles.container}>
      <Head>
        <title>Create Next App</title>
        <link rel='icon' href='/favicon.ico' />
      </Head>

      <main className={styles.main}>
        <h1 className={styles.title}>
          Welcome to <a href='https://nextjs.org'>Next.js!</a>
        </h1>
        <div className={styles.card}>{JSON.stringify(page, null, 2)}</div>
      </main>
    </div>
  );
}

As you can see, we're only fetching a subset of our data and dumping it directly onto the page just to make sure everything is wired up properly. You should see your data dumped to the page as shown below.

It may not seem like it, but a lot of our logic is being handled by getStaticProps() so let's go over it step by step.

We first import any modules we need asynchronously inside of getStaticProps() this is a neat way to ensure that all of this logic only runs on the server at build time.

// asynchronously import neccessary modules and avoid any client side evaluation
const { getPage, getRecordById, getRelatedRecords } = await import(
  "../lib/airtable"
);

Then we query Airtable for the launch page data using the getPage() helper function.

// query inital data from airtable
const [launch] = await getPage("launch");

Which (amongst the rest of the data) returns an array of ids for the seoId field. In this case, the array contains a single id linking to the seo table and pointing to the record with the title "Uptime Monitoring". Take a look at the image below as a refresher for how pages table is related to the seo table.

Recall:

that the title field shown above in the UI is represented as an id in the API response. The API response automatically substitutes the title value in linked records with unique ids instead.

We can use the seoId array to help us query Airtable once more for the related SEO record for your launch page.

// get related seo metadata
if (launch?.fields?.seoId?.length) {
  const seo = await getRelatedRecords("seo", launch?.fields?.seoId);

  if (seo[0]?.fields?.mediaId.length) {
    // get related media for seo og:image
    const ogImage = await getRecordById("media", seo[0]?.fields?.mediaId[0]);
    seo[0].fields.ogImage = ogImage;
  }
  launch.seo = seo;
}

We use the seoId array to fetch the related meta data for the launch page from the seo table. We also check if any media image exists so that we can use it as the og:image for the launch page..

Once we have our data we can return the entire page object as a prop from getStaticProps() which contains all of the related records from each of our responses.

return {
  props: {
    page: launch?.id ? launch : [],
  },
};

Lastly, we access the page prop from our component and dump our data onto the page as JSON.

export default function Home({ page }) {
  return (
    <div className={styles.container}>
      <Head>
        <title>Create Next App</title>
        <link rel='icon' href='/favicon.ico' />
      </Head>

      <main className={styles.main}>
        <h1 className={styles.title}>
          Welcome to <a href='https://nextjs.org'>Next.js!</a>
        </h1>
        <div className={styles.card}>{JSON.stringify(page, null, 2)}</div>
      </main>
    </div>
  );
}

Now that you understand how we're able to fetch data from Airtable with Next.js using getStaticProps(), let's take a look at how that data correlates to the structure of your application.

The diagram below illustrates how each of the fields from your SEO table can be mapped to the corresponding meta tag in your application's HTML markup.

This allows you to make changes in your Airtable base and directly update the structure of your markup resembling the functionality of a CMS.

⚠️ Remember: In development you will see new updates from your Airtable base with each page refresh, but in production, you'll need to rebuild and deploy your application in order to see any changes take effect.

Now that you have an idea of how we'll use the data from your Airtable base as a CMS to render out the initial structure of your application, we can turn our attention back to getting the rest of the related data you'll need to fully build out the Splash page.

We're going to do the same thing we did above to get the related SEO data, but we'll have to make several round trips to the Airtable API in order to get all of the data we need.

First, we'll need to query for all of the sections needed to render the launch page. Then we can iterate over each section to get the related blocks for each section. And while we're iterating, we'll need to do the same for any media image related to each block. We essentially return each responses - all while building up the final page object we'll use to render the application.

All of this logic will be handled within getStaticProps(). Similar to the way we queried for the SEO metadata.

// pages/index.js

export async function getStaticProps() {
  // asynchronously import neccessary modules and avoid any client side evaluation
  const { getPage, getRecordById, getRelatedRecords } = await import(
    "../lib/airtable"
  );

  // query inital data from airtable
  const [launch] = await getPage("launch");

  // get related seo metadata
  if (launch?.fields?.seoId?.length) {
    const seo = await getRelatedRecords("seo", launch?.fields?.seoId);

    if (seo[0]?.fields?.mediaId.length) {
      // get related media for seo og:image
      const ogImage = await getRecordById("media", seo[0]?.fields?.mediaId[0]);
      seo[0].fields.ogImage = ogImage;
    }
    launch.seo = seo;
  }

  // get related data if there is any
  if (launch?.fields?.sectionId?.length) {
    const sections = await getRelatedRecords(
      "sections",
      launch?.fields?.sectionId
    );

    // get all blocks for each section and their related media
    if (sections?.length) {
      launch.sections = await Promise.all(
        await sections.map(async (section) => {
          if (section?.fields?.blockId?.length) {
            const blocks = await getRelatedRecords(
              "blocks",
              section?.fields?.blockId
            );
            if (blocks?.length) {
              section.blocks = await Promise.all(
                await blocks.map(async (block) => {
                  if (block?.fields?.mediaId?.length) {
                    const media = await getRelatedRecords(
                      "media",
                      block?.fields?.mediaId
                    );

                    if (media?.length) {
                      block.media = media;
                    }
                  }
                  return block;
                })
              );
            }
          }
          return section;
        })
      );
    }
  }

  return {
    props: {
      page: launch?.id ? launch : [],
    },
  };
}

☝️ NOTE: that once again we rely on the array of ids we get back from each of the linked record fields to then request each related record by id.

With this in place, you should now be seeing even more data being dumped onto your page as shown in the image below.

Rendering Data From Airtable

Now that you already have all of your data dumped on the client-side of your application you can style and present it however you want to.

For this project, the starter comes with several pre-fabricated components that you can use to render this data. Let's take a look at how these components fit together to make up the structure of your application UI.

As you can see from the diagram above, our index page renders the Splash component, which in turn is responsible for rendering each of the sections in your Splash page.

Each section from your Airtable base maps to a component in your application. We use the type field to determine which component renders each section. The image below shows an example of the mapping between your Airtable fields and the markup used to render them with the Hero component.

The first component your Splash component is responsible for rendering is the Hero component.

// components/Hero.js

import styles from "../styles/Hero.module.css";
import Image from "next/image";

export const Hero = ({ data }) => {
  return (
    <div className={styles.hero}>
      <div className={styles.heroContent}>
        <p className={styles.lead}>{data[0]?.fields?.lead}</p>
        <h1 className={styles.heading}>{data[0]?.fields?.title}</h1>
        <p className={styles.excerpt}>{data[0]?.fields?.excerpt}</p>
      </div>
      {data[0]?.media?.length && (
        <div className={styles.heroImage}>
          <Image
            layout='intrinsic'
            src={data[0]?.media[0]?.fields?.url[0]?.url}
            alt={data[0]?.media[0]?.fields?.alt}
            objectFit='fill'
            width={600}
            height={600}
          />
        </div>
      )}
    </div>
  );
};

The Hero component simply renders a 2 column responsive flexbox layout. If you'll look closely at the markup you'll see that the hero component only accepts thelead, heading, and excerpt fields from your blocks table. It is not templated to render a content field. It will also render the related media image as well.

You can take a look at the styles we use to achieve this layout in styles/Hero.module.css.

☝️ REMINDER: All of the styles for each of the components included with the starter can be found in the /styles directory.

Next.js Image Support

Next.js recently introduced some really powerful image optimizations with their built-in Image component. One of the features we are using for the Hero component above is the layout prop with a value of intrinsic which simply tells Next.js to optimize this image with some basic responsiveness. More on Next.js Image Props.

⚠️ NOTE: There is a caveat the Next.js image component works well out of the box with any images saved locally as an asset in your project to the /public directory, otherwise it needs us to define a domain for any external images so that it understands which domains to optimize for.

This is done by extending the default next.js webpack configuration via a next.config.js file. Under the hood, Next.js will execute file this during the build process and optimize your package bundle with responsive variations of your image.
// next.config.js

module.exports = {
  images: {
    domains: ["dl.airtable.com"],
  },
};
With this in place, Next.js will know to optimize images from this domain. You can also list multiple domains if you're using several resources for image handling

⚠️ NOTE: Your local server will need to be restarted after any changes to your next.config.js file.

Next, we have a List component that is used to render out a list of benefits with icons corresponding to each benefit.

// components/List.js

import Image from "next/image";
import styles from "../styles/List.module.css";

export const List = ({ data, ...rest }) => {
  return (
    <ul className={styles.list}>
      {data?.map((block) => (
        <ListItem
          key={block?.id}
          className={styles.listItem}
          img={block?.media[0]?.fields}
          {...rest}
        >
          {block?.fields?.title}
        </ListItem>
      ))}
    </ul>
  );
};

export const ListItem = ({ img, filter = [], children }) => {
  return (
    <li className={styles.listItem}>
      {filter?.includes("withIcons") && (
        <span className={styles.icon}>
          <Image
            layout='intrinsic'
            src={img?.url[0].url}
            alt={img?.alt}
            width='28px'
            height='28px'
          />
        </span>
      )}
      {children}
    </li>
  );
};

You'll also notice that we're rendering a ListItem for each benefit which includes an icon and some text for each. Each benefit is represented as its own block in AIrtable so we have to iterate over them to render each one out.

The next component we'll need is the Cta component which simply renders a standard signup form for updates regarding your launch.

// components/Cta.js

import styles from "../styles/Cta.module.css";

export const Cta = ({ data, filter = [] }) => {
  const handleSubmit = (e) => {
    e.preventDefault();
    const input = e.target.querySelector("input");
    console.log(input.value);
  };

  return (
    <div className={styles.cta}>
      {data?.map((block) => (
        <div key={block?.id}>
          <h2>{block?.fields?.title}</h2>
          <p>{block?.fields?.excerpt}</p>
          {filter.includes("withForm") && (
            <form onSubmit={handleSubmit}>
              <div className={styles.inputGroup}>
                <input
                  type='email'
                  placeholder='you@youremail.com'
                  required
                  className={styles.input}
                />
                <div className={styles.inputRight}>
                  <button type='submit' className={styles.submit}>
                    Sign up now
                  </button>
                </div>
              </div>
            </form>
          )}
        </div>
      ))}
    </div>
  );
};

Although you have a bit more logic in this component, it's still quite simple.

The component uses the filter field as a modifier to conditionally render a form. This helps us keep the Cta component extendable and reusable with several variations that can be applied from your Airtable response.

For our use case the form simply prints the data out to the console, but you could just as easily send the data to a mailing list provider or other external resources.

The last component we'll need is the Splash component. This component iterates over the page's sections array and renders the appropriate section with the corresponding component.

// components/Splash.js

import { Container, Wrapper, Row } from "./Containers";
import { Hero } from "./Hero";
import { List } from "./List";
import { Cta } from "./Cta";

const components = {
  list: List,
  cta: Cta,
};

export const Splash = ({ data }) => {
  if (!Array.isArray(data)) return null;
  const [hero, ...restComponents] = data;

  return (
    <Wrapper>
      <Container>
        {hero && (
          <Hero
            key={hero?.id}
            data={hero.blocks}
            filter={hero?.fields?.filter}
          />
        )}
        <Row>
          {restComponents.map((section) => {
            const Component = components[section?.fields?.type];

            if (section?.fields?.type.includes("list")) {
              return (
                <Component
                  key={`${section?.id}-${section?.order}`}
                  data={section?.blocks}
                  filter={section?.fields?.filter}
                />
              );
            }
            if (section?.fields?.type.includes("cta")) {
              return (
                <Component
                  key={`${section?.id}-${section?.order}`}
                  data={section?.blocks}
                  filter={section?.fields?.filter}
                />
              );
            }
            return null;
          })}
        </Row>
      </Container>
    </Wrapper>
  );
};

The Splash component gives us some control over which components are used to render each section of our Airtable data. We use the type field to define the component that is used to render this section and the filter field to further add granular control by allowing conditional rendering logic.

There's one final thing left to do. You'll need to render the entire Splash component from pages/index.js.

// pages/index.js

import Head from "next/head";

import { Splash } from "../components/Splash";
import styles from "../styles/Home.module.css";

export default function Home({ page }) {
  console.log();
  return (
    <div className={styles.pageWrapper}>
      <Head>
        <title>{page?.seo[0]?.fields?.title}</title>
        <meta name='viewport' content='initial-scale=1.0, width=device-width' />
        <meta name='description' content={page?.seo[0]?.fields?.description} />
        <meta property='og:title' content={page?.seo[0]?.fields?.title} />
        <meta
          property='og:site_name'
          content={page?.seo[0]?.fields?.sitename}
        />
        <meta property='og:url' content={page?.seo[0]?.fields?.url} />
        <meta
          property='og:description'
          content={page?.seo[0]?.fields?.description}
        />
        <meta
          property='og:image'
          content={page?.seo[0]?.fields?.ogImage?.fields?.url[0]?.url}
        />
        <link rel='icon' href='/favicon.ico' />
        <link rel='cannonical' href={page?.seo[0]?.fields?.url} />
      </Head>

      <main className={styles.main}>
        <Splash data={page?.sections} />
      </main>
    </div>
  );
}

All you have to do pass down your Airtable sections array into the Splash component as props and it handles the rest.

Also Note: We've also implemented search engine optimization using data from our Airtable seo table. This is just a basic implementation and if you're looking for a more robust solution I highly recommend using next-seo for projects that need a more extensible SEO implementation.

Summary

That's it for the first part of the series. I imagine this was a lot to take in, but let's take a quick look at how far we've come in just the first part of our series.

So far you've learned how to implement a custom CMS for your Splash page using Airtable. You also got a close look at how Next.js gives you the ability to perform server-side operations even with static pages at build time making it a great choice for this use case. And we also covered how you can use Next.js for some really simple image optimization.

Next Steps

You've already accomplished a lot already, but I would advise opening up your Airtable base, and from the blocks table start to edit some of your content. You should be able to see your changes reflected in your application after each page load just like you would with any CMS.

Next I'd suggest playing around with the application, and and adding a new section to it. Something like a "founder's message" seems like a good fit.

In the next part of this series, we'll go even further, and take a look at how we can use Sync Inc to synchronize our Airtable base with a cloud Postgres instance. This not only gives your application enterprise-grade scalability but also opens your application up to tons of possibilities including the ability to query your Airtable data with the power and flexibility of raw SQL queries.

So join me for the next installment and be sure to follow me on twitter: @soham_asmi to stay up to date with my latest posts and reach out to me with any feedback or questions.

Until next the next one... 👋

If you enjoyed my content, please feel free to connect with me wherever you spend your time online.

How I Learn...

gshah2020 — Fri, 07 May 2021 19:11:34 +0000

Learning is no simple task. And learning how to learn is no laughing matter.

🤪 Although writing that line did make me chuckle a bit.

For the past 4 years, I have been on a constant journey of learning how to code.

Granted, I was no #codenewbie at the beginning of this process, but I quickly realized I didn't know as much as I thought I did either. When I initially learned to program, we were taught using tools that are no longer even relevant (☠️ RIP Flash).

In those days we built websites with more photoshop than I'd care to admit. Don't believe me?

Check out some of these articles from back in the interweb history, talking about why photoshop is no longer a relevant web design tool:

Design 101: Photoshop for Web Design isn't Just Outdated... it's Bad Practice | Red Branch Media

8 Reasons to Stop Using Photoshop For Web Design

Still curious? Wondering how anyone ever built websites this way? Well, check out this tutorial on creating slices 🔪 from images using photoshop:

https://www.youtube.com/watch?v=DVfxe4pqvo8

Anyway, the point is this wasn't my first foray into web development or scripting for that matter.
ACTIONSCRIPT FTW🤘!
https://en.wikipedia.org/wiki/ActionScript

What changed this time around was my approach. In all my other attempts with web development, I did my damnedest to avoid using code. I used tools that abstracted away from the code layer as much as possible (🤨 I'm looking at you WordPress...).

I guess you could say I was #nocode before #nocode was a thing, 😔 — I wouldn't say it, but I'm sure you could.

For me, the web has always been a creative outlet, and as much as I stared at and played with code it never really clicked for me back then. I thought of coding as more of a supplemental utility, rather than the foundation of my application.

Eventually, my resistance to code and my need for better solutions came to an impasse. I'm sure that every #nocode aficionado even today can sympathize with this sentiment. Somehow this gave me the motivation to learn how to code and eventually started me off on this journey.

Disclaimer

I'm no expert when it comes to coding or learning for that matter, but what happened along the way in the process of learning how to code is that I also ended up developing a framework to help myself learn and intake new data. After years of learning in literally the wrong way, I realized I needed to — learn how to learn — more efficiently.

So my process discussed below is an amalgamation — pieced together from several different widely used learning frameworks and concepts. Personally, none of the frameworks fully addressed my needs. It took a bit of trial and error to lock down a process that worked for me.

So this is the process that has helped me learn more efficiently.

Losing Sight of the Problem

Generally speaking, we as humans often approach learning as a stop in between where we are now and the destination (a.k.a. the skill or knowledge) we want to get to. So we treat it as a means to an end, and in doing so we tend to defeat the entire purpose before we even get started.

The other glaring issue with this approach is that it incentivizes the act of cramming, — here the destination is more like simply passing a test or just building out a partial feature of your application.

My theory is that this occurs because we were never actually committed to the act of learning.

Instead, we are focused on reaching that destination by passing that test or completing that feature. The act of learning, in this example, is like a fleeting pit stop along the way. Instead of retaining the knowledge or developing that skill we simply let it drift away as the moment passes.

And this is where we lose sight of the problem, we spent all that time learning something that will probably end up being a one-trick pony in our toolbelt at best! This is because we never internalized the knowledge to help develop that skill.

The Proposed Solution

I suggest you start by reframing the context, in this approach learning can be a seen EVERY STOP along the way to our destination. Also for the sake of this example, let's imagine the destination is not just a single location, but instead — several locations along the way. And each stop - in between each destination - represents a skill or topic you acquire while traveling from destination to destination.

Learning, in this scenario, becomes an ongoing process, and depending on the topic it could even be looked at as a life-long journey.

In my opinion, this is a healthy starting point for attempting to learn a new topic. It's about the journey, and making the most out of it, not necessarily about the destination and how fast we can get to it.

💡

There are many neurological reasons why this is the case and if you're interested I suggest looking into focused and diffused learning modes. I also posted an article recently that highlights some of the main lessons learned from the discovery of these different learning modes.

By reframing our intention to focus on the process rather than the result, we can now use several common techniques to help us fill in the blanks in our process.

Knowledge Gaps

We all have gaps in our knowledge, this is particularly noticeable when learning an entirely new topic, but even with topics we are already familiar with - we still have some gaps in our knowledge of that topic.

You can't know what you don't know, but now you know... that you don't know.

So how do we being to fill those gaps in our knowledge?

The first step in this approach is to identify 3 things about the subject matter:

What you know.
What you don't know.
What you need to know.

That sounds silly when you say it out loud, but that's the first step, realizing the difference between what you already know, and all of the things you don't know.

One easy way to accomplish this is to pick up a book on the subject and turn to the table of contents. There you go. There's your outline! These are all the things you need to know about this topic (at least, according to this book you've chosen).

💡
You could also look at online courses on the topic and run through their syllabus to achieve a similar outcome.

NOTE: For technical learning, you can usually modify this approach and use the documentation as a reference instead of a book.

As you're going thru each item in the table of contents — make a list, or if you have a physical copy of a book make some marks in the margins. I like to call this process identifying knowledge gaps.

Sometimes you'll approach a topic and there's a prerequisite that you're also unfamiliar with, make a note of this as a blocking topic. You'll need to learn these items first before proceeding to the content you wanted to learn.

For example, you want to learn how to multiply, but you've never be taught how to add. In this scenario, "addition" would be your knowledge gap, you'll need to focus on that first to progress onto the multiplication tables.

Without the fundamental concept of addition, how could you possibly internalize that multiplication is like the shorthand notation for complex repetitive addition tasks?

I'm not saying it isn't possible to learn one without the other, but I will say that you're very likely stacking the deck against you by attempting to do it that way.

As developers we can even utilize larger road maps to help us learn complex interconnected subjects:

https://levelup.gitconnected.com/ultimate-guide-to-web-development-in-2021-beyond-roadmap-2021-6cabbf4edcc0 - @codestackr

https://zerotomastery.io/blog/learn-to-code-in-2020-get-hired-and-have-fun-along-the-way - Ï

https://roadmap.sh - @karanahmed

Scope the Problem

Now that we have an outline in the form of our knowledge gaps, we can take that one step further, and dig back into the book (or reference material) we used to make our outline.

This time around we're going to take each topic we identified as a gap in our knowledge in the last step as and we'll flip to the chapter that discusses it. Now we're going to first flip to the back of that chapter, and see if there are any review questions or a summary there. If we have both, then we're going to read through the summary and attempt to answer the review questions. If it's just a summary read through it and make highlights of important topics.

Several learning frameworks that suggest this approach and it's by far one of my most effective methods of learning.

If we currently lack the knowledge to answer a particular review question, we'll make a note of that, again if you're using a physical book, it makes a lot of sense to highlight the question so that you can refer back to it later.

The last step is to make a quick bullet list in your own words of any topics that you just learned from doing this exercise.

Bonus Points

phrase your bullet points as questions, and write this answer below, this will allow you to turn this new bit of knowledge into flashcards or a quick review tool, later on.

Now you can repeat this step for each item on your knowledge gap list. Iterate through the list and you'll have learned a whole new topic.

You can take as many or as few notes as you feel you need to. I take notes profusely. I record each and every step in the process as a reference.

This helps me create a searchable index of every topic I've attempted to learn. This same data is then available to me no matter what device I am on, it's like having my own mini-wiki.

Diversify

Consume content from multiple sources, take note of the different approaches.

If you used a physical book as a reference in the previous examples, it makes complete sense to look to other sources to fill in some of your more complicated knowledge gaps. This is where a good quick google search will take you a long way. For more complex topics you can try StackOverflow or Reddit.

Dive into some blog posts on specific topics you've identified as your knowledge gaps. Take notes along the way, be sure to constantly summarize everything you learn in your own words. This is the secret sauce.

The act of summarizing alone won't help you remember the content any better, but it will provide you will relatable explanations that you can use as a review. The fact that they were written in your own words means that it will take less processing power on your part the next time you review this material.

In my experience, I learn well through video, so at this stage, I'll usually hop on youtube, and try and see if I can find a video about the specific topic. I don't want an entire course (at least not yet), instead I'm looking for a brief video with a quick overview and an example. I'll take notes through the video and often even follow along if it's something technical.

fireship.io videos are particularly great for this.

Review

Practice makes permanent

Make the reviewing of your notes a daily process, block off a small chunk of time for this once in the morning and once at the end of your day. Be sure to keep adding new material you've learned into the rotation as you progress.

If you phrased your summary bullet points as questions then you can use this free online tool to create flashcards out of that material: quizlet

If you come across any difficult topics that you're having trouble wrapping your head around I suggest opening a discussion somewhere relevant and when in doubt you can ask people on Reddit or Twitter. Be sure to preface the question in the context of "Hey I'm just learning, and I have a few questions...", I find this wards off most internet trolls and invites responses from individuals who understand where you are in your journey.

Build

This part should go without saying, but so many people don't put this into practice, including me. You should build early and often — is a programming sentiment usually expressed about deploying your application, although here it means that we should tinker with the new knowledge we gain along our learning journey at regular intervals.

Did you learn a new way of fetching data? Awesome! Now go back to an older project and implement what you learned again. Do this sooner rather than later, and do it as often as you deem necessary and you will soon begin to experience the effects of those some new neural connections being formed.

I think one of the keys here is to not be afraid to break things in the process and also be open to reaching out for help when you're absolutely stuck.

Teach

This last part is a new addition to my repertoire. I'm genuinely a very introverted person. I tend to be able to get out of my own way - long enough to do what needs to be done, - but choosing to post in a public forum about my learnings and struggles is the last thing I want to do.

So this article is my way of starting on this next part of this journey, by starting a discourse about things I am interested in and things that are most relevant to me.

Going forward, I want to make it a point to post about things I've learned and distill them down in ways people can relate and learn from. Hopefully, this helps someone else out there who is struggling with the topic as I did.

Teaching has long been considered a great way of solidifying the concepts we're still learning. It helps us put the learning into action by forcing us to clarify the concepts in our own minds to help others reach the same understanding.

Summary

I hope this post has helped get you pumped up about applying a learning framework to your learning goals. If you find this information useful, please do feel free to pass it on to someone else who needs it.

Let's just wrap things up with a brief rundown of what we learned in this post:

Learn new things by identifying your knowledge gaps and scoping the problem
Look for supplemental sources of information to help clarify complex topics.
Take quick notes along the way and review those notes daily.
Build things, break them, and ask questions.
Teach, knowledge is meant to be shared - don't be a hoarder.

If you enjoyed my content, please feel free to connect with me wherever you spend your time online.

How we learn...

gshah2020 — Fri, 07 May 2021 17:31:26 +0000

TLDR

Our brains process information in different ways depending on our level of familiarity with the subject matter.
There are two prominent thinking modes, focused and diffuse.
Understanding how our brain can switch context between focused and diffused thinking modes can help us learn new topics more efficiently.
Developing a good learning framework can allow you to transition effectively between these different modes while increasing the length of deep focus times.
Creativity is a product of both of these modes.

Learning is a skill that’s surely best when picked up early in life. I think we can all agree that the process of learning itself is a life-long journey. I often find that when I learn a new subject, the list of what I have to learn grows as I progress through the material. I believe that it's practically impossible to learn everything or even just everything about a single topic in most cases.

And in my experience, I haven't come across a single person that could honestly tell me they knew everything there was to know about a given topic. We have all been learning our entire lives -- and while I can't speak for you -- I know for myself that no one has ever taught me how to learn.

Generally speaking, my idea of learning — was simply cramming as much information as possible — and then applying it as soon as possible. Because I crammed, I had no hopes of retaining that information for longer periods of time. It'll be gone by the time I move on to the next topic. The best I could hope for is to apply it to my work as fast as possible - while it's still fresh in my mind. This indeed points to certain obvious fundamental flaws in not only how I learn, but sadly, how we teach as a society as well.

Just the thought of learning under these circumstances can be an incredibly daunting experience. If we can't reliably expect that we will retain the information that we take in, then doesn't that make this entire process an exercise in futility? Truthfully for me, the answer is a resounding, yes! Continuing to learn this way would be extremely counter-productive, especially when research on the topic has come such a long way.

In recent years, the study of our brains has yielded some intriguing results. I'm no neuroscientist, but thankfully several experts have put together lots of material over the years to help us apply these findings in our everyday lives.

I'm going to do my best to distill these concepts in this post, but if you're interested in understanding how we process information as humans then I can't recommend this free Coursera course enough!

And here's a short clip from that course that introduces this concept by Dr. Barbara Oakley.

Focused vs Diffuse Thinking

Research shows that our brain processes information differently depending on our familiarity with the subject matter. In other words, is this familiar to us? — or is this a brand new topic or skill — which is inherently unfamiliar and new to us? The brain uses two distinctly different modes of thought to process these distinct types of information.

Focused

The focused mode is a processor-intensive function of the brain. It's activated in moments of deep concentration - such as learning a new topic- or during moments of deliberate practice. It occurs when you're tuned into the details of an activity, consciously processing every aspect of it.

When it comes to learning, focused thought can present itself in several ways, I like to think of them as flavors:

Cookies & Cream
focus occurs in moments when you're most engrossed in the subject matter, where it is "resonating with you" and you're able to move freely from topic to topic.
Rocky Road
focus occurs in moments when you're consciously trying to understand a particular topic and you've dedicated your full attention to this task, this relates to information that may be harder to process or a completely new concept/paradigm from what we're used to.

Diffuse

The diffuse mode is used to solidify new concepts and form new neural pathways. It generally, occurs in a semi-resting state when your brain is not actively processing any particular topic and you generally have no conscious control over its processes.

This is similar to muscle memory when comparing with athletes, an athlete perfects a certain "move" with deliberate practice, and over time they get better and faster at repeating that same task until they can perform the "move" effortlessly as if it was second nature.

Neural pathways work similarly in our brains forming new connections between existing skills in our memory and newly learned information processed via focused thought. To achieve this subconscious moves throughout various centers of our brain as relevant skills and information are accessed to form those new pathways. Allowing for this process is the first step to mastery in any subject matter.

The Sweet Spot

When learning you've got to find some structure in your schedule to allow for sessions of both focused and diffused thinking modes to occur organically. This is essential for two main reasons:

We can only deliberately enter the focused mode of thought — there is no surefire way to induce diffuse thinking
Focused thought while powerful, can only be sustained for short periods, as again, this is a very expensive computational process for our brains.
Achieving a balance with focused and diffuse thinking modes can help greatly enhance your creativity.

The Framework

To get better with focus, you can use the Pomodoro technique,

set aside a short specified period of time to take in a new topic. (Generally, I like to work in 25-30min sprints,)
then allow for anywhere between 5-10 mins in between each focus sprint

It's generally recommended to do an activity that gets your mind off of the focused work you were doing. This type of context switching seems to help induce the diffused mode more reliably over time and with practice.

And it could be anything from taking a walk to reading a book or even just talking to some friends/co-workers.

This gives me 25 min of focused time and then (hopefully) another 5-10mins of diffused processing of those thoughts.

The Zone

"The zone" is an elusive place, that sits between the two modes. It's more easily accessed when dealing with familiar information, or when engaging in a repetitive task. It requires certain expertise with the subject which is why people who have mastered a skill to a certain degree often find it easier to get into the zone.

Athletes, artists, and musicians are generally able to access "the zone" more deliberately than students seem to be able to. Math and the sciences are particularly hard to learn and researchers believe this may be due to the abstract nature of the subject matter. Mathematical and scientific symbols create a layer of abstraction that is connected with our intuition, this makes it a more emotional mechanism. This type of input is inherently abstract and therefore neural connections can take longer periods to form, and usually require considerable repetition to solidify each new concept.

Practice Makes Permanent

This is why repetition is key to learning these more abstract topics, actively engaging in the act of recall, which helps trigger the process of forming new neural pathways. This is similar to how athletes or musicians develop muscle memory through repetitive practice.

While we're on the topic of practice, here's a TEDx Talk on learning that discusses some of the importance of practice...

When in the zone, you're intensely focused on the task at hand through a form of tunneled focus, thoughts and input are processed seemingly instantaneously through your subconscious. This gives you access to a "limbo state" where you can benefit from the best of both modes!

Many historically famous individuals have used various techniques to force their brains to transition from one mode to the other. Most of them are just different ways of tricking the brain to go into diffused thinking mode by triggering a resting state to access the diffused mode and then using that as momentum to jump into focused thought or deliberate practice on a particular subject.

The issue here is that these moments can only be sustained for short periods (if and when you're able to trigger them). Because of this your results will vary and are therefore not reliable.

I think the key for those of us on the learning journey should instead to be find a balance between the two modes provide ample time for each process to take hold and have an effect on our overall learning progress. This is how bodybuilders approach building muscle, by working out different parts of their body on different days.

In our case, as it applies to learning, it's more about deliberately using focused thought to take in information, while allowing ample time in between for rest periods so that our brain can effectively process the information and form relevant new neural connections for us.

I've also found it very helpful to apply the learnings immediately after a rest period, rather than moving onto the next topic. It seems that when I do learn this way, I tend to have better access to the material.

The Flow

But in psychology circles, there's this concept of the "flow state" — which is similar to the zone, although I like to think of it as being "deep in the zone".

This is where your focus and diffused thought modes are seemingly on auto-pilot, and you're essentially just along for the ride, your brain does most of the heavy lifting -- taking in sensory input and processing information on the fly -- which allows your creativity to surface and flow.

Ideally being in the flow is like - you getting out of your own way. You're not overthinking, you're not under-thinking. In fact, you're barely thinking at all. You're simply flowing, or should I say, going with the flow.

This realization eventually reminded me of a Tedx talk (thanks to what I believe was a new neural pathway forming...) by Dandapani, which talked about concentration as it relates to meditation. He elaborates on some of the same concepts I've discussed here in a brilliantly simple way with a focus exercise you can follow along with towards the end. I highly recommend watching it the whole way through.

TEDx - Dandapani)

So there you have it, I hope that you'll use this information to your benefit and apply this to your learning journey. There's a lot to learn and not a moment to lose, so get started today!

If you've found this post helpful, I suggest digging deeper into the subject since I'm no expert on the matter, you must do your own research and find ways that you can best apply this to your learning in the way that best suits your needs.

If you enjoyed my content, please feel free to connect with me wherever you spend your time online.

Full Stack GraphQL

gshah2020 — Tue, 01 Dec 2020 18:50:34 +0000

[Starter-Repo]

What is Graphql?

a "spec" that describes a declarative query language that your clients can use to ask an API for the exact data they want. This is achieved by creating a strongly typed Schema for your API, ultimate flexibility in how your API can resolve data, and client queries validated against your Schema.

Core Concepts

Graphql can be quite different based on how it is handled on the server-side vs. in client-side applications.

Server Side

On the server side graphql is about creating a graph based on the shapes of some objects that you'd like to expose to the web in the form of an api. This allows your users to query that graph in whatever manner they need. You have no control of what data is fetched when, the client dictates that at the time of making a request.

Client Side

Client side graphql operations mainly revolve around the fetching the exact data needed by various application. Clients make requests for data using queries and mutations which allow clients to ask for specific data and even manipulate that data.

Server-Side Config

Schema

typeDefs - since graphql is a strongly typed framework, it requires a strict typeDef of each part of your data.

resolvers - similiar to controllers in a REST api, and are responsible to retrieving data from a data-source. Whether that is a database, in memory, cache or even other apis.

query definitions - queries are are another type in graphql which the client side will primarily use in order to format their request body to meet the needs and demands of their particular application and use-case.

mutation definitions - similar to handers from a REST api, and are functions used for returning values for fields that exist on Types in a Schema. Resolver execution is dependent on the incoming client query.

composition - the ability to compose different apis together underneath a single graphql umbrella.

schema - all of the above components are combined to form a graphql schema, which is a similar to a snapshot of the data your api handles and instructions on how it will handle that data when responding to specific requests.

fragments - similar to partials in some front-end rendering libraries, fragments allow the required logic for queries and mutations to not overly repeat itself. When working with same/similar data there can be a lot of re-use, and fragments facilitate that ability.

Creating a Schema

Schemas are created using (SDL ) Schema Definition Language. Primarily this is used to define our graphql types, such as our queries, resolvers, and mutations.

☝️ Schemas can also be programmatically created using language constructs. In javascript these are funtions that return our schema.

Types - a construct defining a shape with fields
Fields - keys on a Type that have a name and value type
Scalars - primitive value type built into GraphQL
Query - type that defines operations clients can perform based on schema
Mutation - type that defines ouw clients can modify or create data

GraphQL Hello World Server

Minimal ApolloServer

// converts a template string into a graphql schema
const gql = require("graphql-tag"); 
// https://tinyurl.com/lxpwd2z

// graphql server
const { ApolloServer } = require("apollo-server"); 
// https://tinyurl.com/y3akd5kh

// schema definitons:
const typeDefs = gql`
  type User { # describes the shape of the User type
    # non-nullable fields ('!')
    email: String!
    avatar: String!
    friends: [User!]! # array of users, should always return an array of users
  }

  type Msg {
    title: "String!"
  }

  type Query { # used to define data requested from api
    me: User!
    msg: Msg!
  }
`;

const resolvers = {
  //creates a 1to1 mapping for each query defined above
  Query: {
    me() {
      // resolver for the 'me' query
      return {
        // hard-coded resolved dummy data
        email: "myemail@email.com",
        avatar: "https://source.unsplash.com/random",
        friends: [],
      };
    },
    msg() {
      return {
        title: "\"this is a default message\","
      };
    },
  },
};

// server is instantiated wtih typeDefs and resolvers
const server = new ApolloServer({
  typeDefs,
  resolvers,
  ctx() { // creates a context object on our server:
    return { models }; // allows resolvers and muations to access models
  },
});


server.listen(4000).then(() => console.log("server running on port 4000"));

As we see above the minimum things we need to build a graphql server:

A Query Type

with at least one field

And a resolver for any field queries

Which is basically saying we need a Schema with atleast one query and resolver present.

Resolver Signature

fieldName: (parent, args, context, info) => data;

Argument	Description
`parent`	This is the return value of the resolver for this field's parent (the resolver for a parent field always executes before the resolvers for that field's children).
`args`	This object contains all GraphQL arguments provided for this field.
`context`	This object is shared across all resolvers that execute for a particular operation. Use this to share per-operation state, such as authentication information and access to data sources.
`info`	This contains information about the execution state of the operation (used only in advanced cases).

Resolver Arguments

@param: initialValue (aka - "parent", "_")

Query: {
  demo(initialValue, )
}

initial value contains the parent resolvers context, this is because queries are executed in heirachical succesion, so the child query retains access to the parent query's context. and that is accessible as initialValue from any child query.

☝️ NOTE: top-level queries will not have any relationships above them as no other queries get resolved before them. So initialValue will be null for all top-level queries.
Query: {
  demo(_, )
}
⚠️ You may see this represented as an underscore: ( _ ). This simply tells us that this function is ignoring this argument, and makes no use of it.

@param: arguments (aka - "args", "_ _")

Query: {
  demo(_, arguments)
}

arguments - contains any arguments that get passed into our mutations and queries, if any when there are any.

☝️NOTE: When the query or mutation doesn't make use of the arguments object it can also be represented with two underscores: (_ _)

❗️ IMPORTANT: expected arguments must be defind in the Schema, graphql will not have the ability to handle any unknown arguments, it will only act on arguments that is has prior knowledge of how to handle.

Arguments can be added to any field (if necessary)
  type Query {
      pets(type: String!): [Pet]
  }
Here the pets query takes an argument that is a String, which sets the type of the pet.

This can be accessed from our resolvers as:
Query: {
  pets(_, { type }, ctx) {
    return [/* pets */]
  }
}
Must be either an Input or Scalar Type.

@param: context (aka - "ctx")

Query: {
  demo(_, __, context)
}

An object exposed manually through our apollo server which allows us to access things like our models and database from our resolvers.

☝️ Context must be instantiated on the server along with resolvers and typeDefs:
// api/src/server.js

const server = new ApolloServer({
  typeDefs,
  resolvers,
  ctx() {
    return { models };
  },
});

@param: info (aka - "ast")

Contains the abstract syntax tree of the current model. Contains information about the operation's execution state, including the field name, the path to the field from the root, and more.

⚠️ This param is rarely used.

Input Types

Input Types are field definitions that can be re-used to populate the arguments necessary for different resolvers.

💡 Think of them as Types for arguments.

All field values of input types must be either other Input Types or Scalars

// api/src/schema.js
input PetInput {
  name: String # optional
  type: String # optional
}

This can be used to populate the input field arguments for our pets resolver definition:

// api/src/schema.js

type Query {
  pets(input: PetInput): [Pet]!
}

And now this will be available on our pets resolver as input:

// api/src/resolvers.js

Query: {
    me(parent, args, context) {
      console.log(parent, args, context);
      return {
        id: "oajsdfkla",
        username: "bob1",
      };
    },
    pets(parent, { input }, { models }) {
      console.log(input, models);
      const pets = models.Pet.findMany(input || {});
      return pets;
    },
  },
}

Finally we can query for this data using our gql playground:

# playground query

{
  pets(input: { name: "Fido", type: "Wolf" }){
      id
      createdAt
      name
      type
  }
}

❗️Must use double quotes ("") in input field arguments

Challenge

define query type for the user and pet model in api/src/db/schema.js

  {
    "user": {
      "id": "string",
      "username": "string"
    },
    "pet":{
      "id": "string",
      "createdAt": "number",
      "name": "string",
      "type": "string"
    }
  }

create query type for retrieving an array of pets
instantiate apollo server with required typeDefs and resolvers

// api/src/db/schema.js

const { gql } = require("apollo-server");

const typeDefs = gql`
  type User {
    id: String!
    username: String!
  }

  type Pet {
    id: String!
    createdAt: Int!
    name: String
    type: String!
  }
  type Query {
    me: User!
    pet: Pet!
  }
`;

module.exports = typeDefs;

// api/src/resolvers.js

module.exports = {
  Query: {
    me() {
      return {
        id: "oajsdfkla",
        username: "bob1",
      };
    },
    pet() {
      return [
        {
          id: "lkajsdflkjasdflkj",
          createdAt: Date.now(),
          name: "fido",
          type: "mini wolf",
        },
      ];
    },
  },
};

returns hard-coded data matching each resolvers expected output.

// api/src/server.js

const { ApolloServer } = require("apollo-server");
const typeDefs = require("./schema");
const resolvers = require("./resolvers");
const { models, db } = require("./db");


// add models to apollo-context so that they are available via mutations && resolvers:
const server = new ApolloServer({
  typeDefs,
  resolvers,
  context() {
    return { models };
  },
});



server.listen().then(({ url }) => {
  console.log(`🚀 Server ready at ${url}`);
});

🛠 FIX: pets query not resolving can't read the model from context??
{
  "errors": [
    {
      "message": "Cannot read property 'Pet' of undefined",
    }
  ]
}

Query arguments:

  type Query {
    me: User!
    pets(input: PetInput): [Pet]! # takes optional resolvers defint by PetInput
    pet(input: PetInput): Pet # returns a single pet
  }

    pets(_, { input }, { models }) {
      const pets = models.Pet.findMany(input); // uses input to populate db query
      return pets;
    },
    pet(_, { input }, { models }) {
      const pets = models.Pet.findOne(input); // uses input to populate db query
      return pets;
    },

uses the input arguments to allow us to search for matching data from database

Mutations

A Type on a Schema that defines operations a client can perform to mutate data (CRUD).

Creating Mutations

Define Mutation Type on Schema
Add fields for Mutation Type
Add arguments for Mutation fields (mutations will likely always require arguments)
Create Resolvers for Mutation fields

const typeDefs = gql`
    #########

    input NewShoeInput {
    brand: String!
    size: Int!
  }

  type Mutation {
    newShoe(input: NewShoeInput!): Shoe!
  }

    ##########
`    

  const resolvers = {
    Query: {
      /*...*/
    },
    Mutation: {
      newShoe(_, { input }) {
        shoes.push(input);
        console.log(shoes);
        return input;
      },
    },
  }

Challenge

Create a mutation to create a new pet:

// api/src/schema.js

    type Mutation {
    createPet(input: PetInput): Pet!
  }

// api/src/resolvers.js  
  Mutation: {
    createPet(_, { input }, { models }) {
      const newPet = models.Pet.create(input);
      return newPet;
    },
  },

Advanced SDL (Schema Definition Language)

Enums

A set of discrete values that can be used in place of Scalars. An enum field must resolve to one of the values in the Enum. Great for limiting a field to only a few different options.

☝️ By default Enums resolve to a string.

const typeDefs = gql`
  enum ShoeType {
    JORDAN
    NIKE
    ADIDAS
  }
  type Shoe {
    brand: ShoeType!
    size: Int!
  }
`

Now we have limited the types to only the ones we've listed in our enum as options.

Interfaces

Abstract Types that can't be used as field values, but instead are used as foundations for explicit Types. Great for when you have Types that share common fields, but differ slightly.

  interface Shoe {
    brand: ShoeType!
    size: Int!
  }
  type Sneaker implements Shoe {
    brand: ShoeType!
    size: Int!
    sport: String!
  }
  type Boot implements Shoe {
    brand: ShoeType!
    size: Int!
    hasGrip: Boolean!
  }

❗️ The real power of this isn't felt in our definitions, but rather when we make queries. A type that implements an interface doesn't require new query definitions. We can define all of our queries for Shoes, and they will also apply to Sneakers.

🤔 Think of Javascript Class constructors and how they can extend functionality from a parent class. This seems to work in a similar fashion.

❗️NOTE: You can not query an interface directly, a Shoe in our current example will always resolver to either a Sneaker or a Boot.

Interface Resolver Types

⚠️ We'll need to teach our resolvers how to determine whether they are resolving to a boot or a sneaker in the above use case. We even get a warning in the console that instructs us accordingly:

Type "Shoe" is missing a "__resolveType" resolver. Pass false into "resolverValidationOptions.requireResolversForResolveType" to disable this warning.
server running on port 4000

note that the server is still running and didn't fail to start.

In order to resolve our shoe type, we'll need to create a custom resolver with the __resolveType method:

const resolvers = {
  /*...*/
  Shoe: {
    __resolveType(shoe) {
      if(shoe.sport) return 'Sneaker'
      return 'Boot'
    }  
  }
}

⚠️ If there is an error in this setup, you'll likely see the following error:
Abstract type X must resolve to an Object type at runtime 

Either the X type should provide a \"resolveType\" function or each possible type should provide an \"isTypeOf\" function."

Querying for Type specific fields of an Interface

We also get access to the typeName in our queries:

*☝️NOTE: * it seems that the __typename seems to only run once, even though we've defined it for the shoe itself and then for each type of shoe. This is because graphql de-dupes our fields automatically.

Unions

Like interfaces, but without any defined common fields amongst the Types. Useful when you need to access more than one disjoint Type from Query, like a search.

The Union type indicates that a field can return more than one object type, but doesn't define specific fields itself

  type Sneaker {
    brand: ShoeType!
    size: Int!
    sport: String!
  }
  type Boot{
    brand: ShoeType!
    size: Int!
    hasGrip: Boolean!
  }

  union FootWear = Sneaker | Boot

  FootWear: {
    // required to resolve the type of the interface:
    __resolveType(shoe) {
      // returns the type name as a string
      if (shoe.sport) return "Sneaker";
      return "Boot";
    },
  },

Combining Interfaces and Unions:

  interface Shoe {
    brand: ShoeType!
    size: Int!
  }
  type Sneaker implements Shoe {
    brand: ShoeType!
    size: Int!
    sport: String!
  }
  type Boot implements Shoe {
    brand: ShoeType!
    size: Int!
    hasGrip: Boolean!
  }
  union FootWear = Sneaker | Boot

    FootWear: {
    // required to resolve the type of the interface:
    __resolveType(shoe) {
      // returns the type name as a string
      if (shoe.sport) return "Sneaker";
      return "Boot";
    },
  },
  Shoe: {
    // required to resolve the type of the interface:
    __resolveType(shoe) {
      // returns the type name as a string
      if (shoe.sport) return "Sneaker";
      return "Boot";
    },
  },

Relationships

Thinking in Graphs

Your API is no longer a predefined list of operations that always return the same shapes. Instead, your API is a set of Nodes that know how to resolve themselves and contain links to toher related Nodes. This allows a client to ask for Nodes and then follow those links to get related Nodes.

Adding Relationships

Add a Type as a field value on another Type
Create resolvers for those fields on the Type

First we'll update our data, so that we can grab a reference to users who own our shoes:

const shoes = [
  // 🚧
  { brand: "NIKE", size: "11", sport: "basketball", user: 1 },
  { brand: "ADIDAS", size: "19", sport: "soccer", user: 2 },
  { brand: "TIMBERLAND", size: "10", hasGrip: true, user: 3 },
];

Next let's update our current schema:

  type User { # describes the shape of the User type
    # non-nullable fields ('!')
    id: Int! # 🚧
    email: String!
    avatar: String!
    shoes: [Shoe]! # 🚧
  }
  interface Shoe {
    brand: ShoeType!
    size: Int!
    user: User!
  }
  type Sneaker implements Shoe {
    brand: ShoeType!
    size: Int!
    user: User!
    sport: String!
  }
  type Boot implements Shoe {
    brand: ShoeType!
    size: Int!
    user: User!
    hasGrip: Boolean!
  }
  union FootWear = Sneaker | Boot

const resolvers = {
    /*...*/
  Shoe: {
    // required to resolve the type of the interface:
    __resolveType(shoe) {
      // returns the type name as a string
      if (shoe.sport) return "Sneaker";
      return "Boot";
    },
    user(shoe) {
      return user;
    },
  },
  Sneaker: {
    user(shoe) {
      return user;
    },
  },
  Boot: {
    user(shoe) {
      return user;
    },
  },
}

Note that we were not able to create the resolver for user on the Abstract Object (interface) Shoe. Instead we must individually resolve each of the types that implement our interface, in this case: "Boot" and "Sneaker"

We can also query the interface alone:

We can also use our new definitions to do other relational queries by adding a User resolver to help resolve shoes that belong to this specific user:

const resolvers = {
  /*...*/
  User: {
    shoes(user) {
      return shoes.filter((shoe) => shoe.user !== user.id);
    },
  },
  /*...*/
}

⚠️ This type of logic causes endless recursion:

Challenge

A pet should have an associated user
A user should also contain an array of pets.

Create resolvers to handle the related data

First, we'll want to add the user field to our pet instances in the db:

    {
      "id": 1,
      "createdAt": "10-24-2020",
      "name": "fido",
      "type": "DOG",
      "user": "jBWMVGjm50l6LGwepDoty"
    },

Nextwe'll need to ensure we expose our current user to our context:

// api/src/server.js

  context() {
    const user = models.User.findOne({ username: "frontendmaster" });
    return { models, db, user };
  },

Next we can update our schema:

  type User {
    id: String!
    username: String!
    pets: [Pet]! # 🚧
  }

  type Pet {
    id: String!
    createdAt: String!
    name: String!
    type: String!
    user: User! # 🚧
  }

And lastly we'll need to add resolvers for each type to resolver to the correct data for our new fields:

  Pet: {
    owner(pet, __, { models }) {
      // normally we'd have to find the matching user, but we only have one user in the db
      return models.User.findOne();
    },
  },
  User: {
    pets(_, __, { models, user }) {
      // return models.Pet.findMany({ user: user.id });
      return models.Pet.findMany();
    },
  },

Client Side Config

As we saw in the server-side section queries and mutations get defined on the server-side of any graphql application, but from the front end we then have to execute those queries and mutations to interact wtih our data.

Operation Names

Unique names for your client side Query and Mutation operations. Used for client-side caching, indexing inside of tools like GraphQl Playground.. Like naming your functions in JS vs keeping them anonymous.

Variables with operations

Operations can define arugments, very much like a function in most programming languages. Those variables can then be passed to query/mutation calls inside the operation as arguments. Variables are expected to be given at run time during operation execution from your client.

query AllCharacters {
  characters(page: 2) {
      results {
          name
      }
  }
}
I this query we're using a query variable called page, and we've currently hard coded it with the value '2', to help us target the second page of characters from this api.

We can also use query variables in graphql playgorund to help us test our queries that accept certain variable arguments:
query AllCharacters($page: Int) {
  characters(page: $page) {
      results {
          name
      }
  }
}
In this example we've created a variable called $page instead of head coding it.

☝️ NOTE: it is initially defined after the operation name and used in our characters query

query varibles are scoped to the actual operation itself and can be used anywhere inside of them (when applicable):
query AllCharacters($page: Int, $id: String) {
  characters(page: $page) {
      results {
          name (id: $id)
      }
  }
}

Aliasing Queries and Mutations

Used to rename fields so that they match the shape expected by our clientside application.

Also an example of a filter operation using query variables

We can also run multiple queries together:

Apollo Client

Encapsulates HTTP logic used to interact with a GraphQL API. Doubles as a client side state management alternative as well (such as: Redux, MobX, etc...).

If your GraphQL API is also an Apollo Server, provies some extra features. Offers a plug-in approach for extending it's capabilities. It's also framework-independent.

☝️ Note that we can use graphql to handle local application state, as an alternative to local state management.

Storing Data from your API

All nodes (fields returned from a query) are stored flat by an unique ID
Unique ID is default to .id or ._id, from nodes. You can alter this behavior
Every node should send an .id or ._id, or none at all.
- Or you can add custom logic to handle the id reference.

Queries in React

Setup Apollo Client

// client/src/client.js

import { ApolloClient } from "apollo-client";
import { InMemoryCache } from "apollo-cache-inmemory";
import { HttpLink } from "apollo-link-http";
import gql from "graphql-tag";

// network interface to access gql server -- link to gql connection
const link = new HttpLink({ uri: "http://localhost:4000" });
// sets up apollos in-memory-caching
const cache = new InMemoryCache();

// client takes the httplink and the cache as an argument
const client = new ApolloClient({ link, cache });

export default client;

Testing External Queries:

// client/src/client.js

const link = new HttpLink({ uri: "https://rickandmortyapi.com/graphql" });


const query = gql`
  {
    characters {
      results {
        id
        name
      }
    }
  }
`;

client.query({ query }).then((results) => console.log(results));

Let's update our client uri once again:

// client/client.js

const link = new HttpLink({ uri: "http://localhost:4000" });

Then we can use this to provide our client to our application:

// client/index.js

import { ApolloProvider } from "@apollo/react-hooks";
import client from "./client";


const Root = () => (
  <ApolloProvider client={client}>

    <BrowserRouter>
      <App />
    </BrowserRouter>

  </ApolloProvider>
);

With this in place we've now gained access to the Apollo-dev-tools in our browser as well.

This allows us to access our queries, mutations, and cache as well as the GraphiQL interface.

Now we can use the useQuery hook form apollo to help us qeury for our data:

// client/src/pages/Pets.js


export default function Pets() {
  const [modal, setModal] = useState(false);

  const MY_PETS = gql`
    query MyPets {
      pets {
        id
        name
      }
    }
  `;

  const { data, loading, error } = useQuery(MY_PETS);
  if (loading) return <p>Loading...</p>;
  if (error) return `XError! ${error.message}`;

  return (
    <div className='page pets-page'>
        {/*...*/}
      <section>
        <div className='row'>
          <PetsList pets={data.pets} />
        </div>
      </section>

    </div>
  );
}

Mutations

mutation CreateAPet ($newPet: NewPetInput!) {
  createPet(input: $newPet) {
    id
    name
    type
  }
}

Client Side Variables for mutations

// client/src/pages/Pets.js


   const NEW_PET = gql`
    mutation CreateAPet($newPet: NewPetInput!) {
      createPet(input: $newPet) {
        id
        name
        type
      }
    }
  `;


  const [createPet, newPet] = useMutation(NEW_PET);
  if (loading || newPet.loading) return <Loader />;
  if (error || newPet.error)
    return `XError! ${error && error.message} ${
      newPet.error && newPet.error.message
    }`;

  const onSubmit = (input) => {
    // input contains the values from our form: {name, type}
    setModal(false);
    createPet({ variables: { newPet: input } });
  };

Currently we're able to create a new pet, although our page does not respond to the new data and so we actually have to do a refresh to get the new data.

Why is Cache out of sync?

If you perform a mutation that updates or creates a single node, then apollo will update your cache automatically given the mutation and query have the same fiields and id.

⚠️ Always ty to match the fields on mutations and queries 1to1, this let's us opt into apollo's default caching behavior

This is also why when we create a new pet apollo doesn't refresh the page, because it has never cached that item yet since it was just created. Which is why refreshing does pull down the item.

⚠️ This is also the case when we're deleting

If you perofrm a mutation that updates a node in a list or removes a node, you are responsible for updating any queries referencing that list or node. There are many ways to do this with apollo.

Keeping Cache in Sync

Refetch matching queries after a mutation
use update method on mutation (recommended)
watch queries

Refetch

Refetching enables you to refresh query results in response to a particular user action, as opposed to using a fixed interval.

Update method

  const [createPet, newPet] = useMutation(NEW_PET, {
    update(cache, { data: { createPet } }) {
      const data = cache.readQuery({ query: ALL_PETS });
      cache.writeQuery({
        query: ALL_PETS,
        data: { pets: [createPet, ...data.pets] },
      });
    },
  });

In this approach we're manually handling the caching so that we can run an update using our query, which will allow us to re-load our data after a mutation occurs.

Watch Query

Provide this object to set application-wide default values for options you can provide to the watchQuery, query, and mutate functions.

Note: The useQuery hook uses Apollo Client's watchQuery function. To set defaultOptions when using the useQuery hook, make sure to set them under the defaultOptions.watchQuery property.

const defaultOptions = {
  watchQuery: {
    fetchPolicy: 'cache-and-network',
    errorPolicy: 'ignore',
  },
  query: {
    fetchPolicy: 'network-only',
    errorPolicy: 'all',
  },
  mutate: {
    errorPolicy: 'all',
  },
};

watchQuery(options)

This watches the cache store of the query according to the options specified and returns an ObservableQuery. We can subscribe to this ObservableQuery and receive updated results through a GraphQL observer when the cache store changes.

NAME / TYPE DESCRIPTION

contextany Context to be passed to link execution chain

errorPolicy`"none" "ignore"

{% raw %}fetchPolicy`"cache-first" "network-only"

{% raw %}nextFetchPolicyany Specifies the FetchPolicy to be used after this query has completed.

notifyOnNetworkStatusChangeany Whether or not updates to the network status should trigger next on the observer of this query

partialRefetchany If true, perform a query refetch if the query result is marked as being partial, and the returned data is reset to an empty Object by the Apollo Client QueryManager (due to a cache miss).

pollIntervalany The time interval (in milliseconds) on which this query should be refetched from the server.

query`DocumentNode TypedDocumentNode`

returnPartialDataany Allow returning incomplete data from the cache when a larger query cannot be fully satisfied by the cache, instead of returning nothing.

variablesTVariables A map going from variable name to variable value, where the variables are used within the GraphQL query.

NAME / TYPE	DESCRIPTION
`contextany`	Context to be passed to link execution chain
`errorPolicy``"none"	"ignore"
{% raw %}`fetchPolicy``"cache-first"	"network-only"
{% raw %}`nextFetchPolicyany`	Specifies the FetchPolicy to be used after this query has completed.
`notifyOnNetworkStatusChangeany`	Whether or not updates to the network status should trigger next on the observer of this query
`partialRefetchany`	If `true`, perform a query `refetch` if the query result is marked as being partial, and the returned data is reset to an empty Object by the Apollo Client `QueryManager` (due to a cache miss).
`pollIntervalany`	The time interval (in milliseconds) on which this query should be refetched from the server.
`query``DocumentNode	TypedDocumentNode`
`returnPartialDataany`	Allow returning incomplete data from the cache when a larger query cannot be fully satisfied by the cache, instead of returning nothing.
`variablesTVariables`	A map going from variable name to variable value, where the variables are used within the GraphQL query.

Optimistic UI

Your UI does not have to wait until after a mutation operation to update itself. Instead, it anticipates the response from the API and process as if the API call was in sync. The API response replace the generated response. This gives the illusion of your app being really fast.

Optimistic UI is a pattern that you can use to simulate the results of a mutation and update the UI even before receiving a response from the server. Once the response is received from the server, the optimistic result is thrown away and replaced with the actual result.

☝️ Loading Skeletons > Loading Spinners

// client/src/client.js


import { ApolloClient } from "apollo-client";
import { InMemoryCache } from "apollo-cache-inmemory";
import { HttpLink } from "apollo-link-http";
import { ApolloLink } from "apollo-link";
import { setContext } from "apollo-link-context";

import gql from "graphql-tag";

// network interface to access gql server -- link to gql connection
const http = new HttpLink({ uri: "http://localhost:4000" });

// create test for slower networks using apollo:
const delay = setContext(
  (request) =>
    new Promise((success, fail) => {
      setTimeout(() => {
        success();
      }, 800);
    })
);

// combines the usage of httplink && apollo link to a single link reference:
const link = ApolloLink.from([delay, http]);

// sets up apollos in-memory-caching
const cache = new InMemoryCache();

// client takes the httplink (from our custom link) and the cache as an argument
const client = new ApolloClient({ link, cache });

export default client;

here we've simply taken the HttpLink that the client needs to intantiate ApolloClient and added a reference to a delay paramter using setContext from apollo. This allows us to simulate slow network requests, with our given delay parameter.

Now we can use this in our application and we can test our optimistic response setup using the delay we've configured so that the loading states will last longer than normal while in development mode.

// client/src/Pets.js

 const onSubmit = (input) => {
    setModal(false);
    createPet({
      variables: { newPet: input },
      optimisticResponse: {
        // used to render updated ui while graphql syncs db
        __typename: "Mutation", // operation type
        createPet: {
          // matches the resolver name
          id: "this-id-does-not-matter-here", // if id is available include -- gets replaced with new data from mutation
          __typename: "Pet", // include all expected fields,
          // these will be used to populate the data until the actuam mutation occurs/updates.
          type: input.type,
          name: input.name,
        },
      },
    });
  };

optimisticResponse is a property we can set from our mutation's update functions.

Since we're taking advantage of the optimistic UI rendering, it's only good practice to remove any loading state handlers.
  // ❌ if (loading || newPet.loading) return <Loader />;
  if (loading) return <Loader />;
Remove newPet Loading state to opt out of loading state in favor of optimistic rendering.

☝️ NOTE we removed the loading handler for only our newPet mutation loading state, this is because we're looking to render it optimistically and if were to keep the loading state in place, it would flicker in very quickly as the state of our hook went from loading: true => loading: false.

Client Side Schemas

In addition to managing data from your API, apollo client can also be used to manage local state originating from our front end client side application.

Think of it as an alternative to reach for redux or other state management/machine libraries.

You can create a schema to define that state which allows you to query for that state the same way you query you api for data.

☝️ The approach here is very similar to creating schema for the backend of your application, you'll need the same two things to get started:

typeDefs

resolvers

// client/src/client.js

// extend backend types with front-end schema. 
const typeDefs = gql`
    extend type User {
        age: int
    }
`

const resolvers = {
  User: {
    age() {
      return 3 // hard-coded repsonse
        }
  }
}

// ❌ const client = new ApolloClient({ link, cache }); 
const client = new ApolloClient({ link, cache, resolvers, typeDefs });

Now we can update our query to incorporate our changes:

// client/pages/Pets.js

  const ALL_PETS = gql`
    query allPets {
      pets {
        id
        type
        name
                owner {
                    id
                    age @client
                }
      }
    }
  `;

The @directive @client tells apollo that this field gets resolved on the client-side only. It will simply ignore this field for any backend only operations and still allow us to use it on the front end as a piece of local state related to our user.

Fragments

A GraphQL fragment is a reusable part of the query. A GraphQL fragment lets you build multiple fields, and include them in multiple queries.

# fragment ownerInfo for RepositoryOwner fields

fragment ownerInfo on RepositoryOwner {
  id
  avatarUrl
  resourcePath
  url
}

// GraphQL Query with fragments used in multiple queries

{
  googleRepo: repository(owner: "google", name: "WebFundamentals") {
    name
    owner {
      ...ownerInfo //fragment
    }
  }
  facebookRepo: repository(owner: "facebook", name: "react") {
    name
    owner {
     ...ownerInfo //fragment
    }
  }
}

A fragment consists of three unique components:

Name: This is the unique name of the fragment (each fragment can have its own name)

TypeName: The type of object the fragment is going to be used on. This indicates which nested object, from the GraphQL schema, this fragment is created on

Body: The last part is the body of the fragment. The body of the fragment defines the fields that will be queried for

So why are fragments cool within a GrapQL query?

Reusability – With fragments, you can organize your queries into reusable units

Caching – GraphQL clients make use of fragments, to provide caching options

// client/src/pages/Pets.js

  const PETS_FIELDS = gql`
    fragment PetsFields on Pet {
      id
      name
      type
      vaccinated
    }
  `;

// usage:

  const ALL_PETS = gql`
    query allPets {
      pets {
        ...PetFields
      }
    }
    ${PET_FIELDS}
  `;

  const NEW_PET = gql`
    mutation CreateAPet($newPet: NewPetInput!) {
      createPet(input: $newPet) {
        ...PetFields
      }
    }
    ${PET_FIELDS}
  `;

Challenge:

Extend Pet Type with new Field: Vaccinated

  // client/src/client.js


  const typeDefs = gql`
    extend type Pet {
      vacinated: Boolean!
    }
  `;

  const resolvers = {
    Pet: {
      vacinated: () => true
    }
  };
  ```




- Fragment for pet type

- Update fragment to exist for both ALL_PETS query and NEW_PET mutation




---

Hey everyone, I'm Gaurang, a full-stack developer that is constantly learning and building in public. I love that I was able to change my career at such a late stage in life all by learning online with so many different resources. I generate content to reinforce what I'm learning and to help others like me in the future.

If you enjoyed my content, please feel free to connect with me [wherever you spend your time online](https://links.gshahdev.com/all-links).

Strapi CMS Notes

gshah2020 — Tue, 01 Dec 2020 18:46:06 +0000

https://strapi-showcase.s3-us-west-2.amazonaws.com/CheatSheet.pdf

Install with postgres:
npx create-strapi-app backend
? Choose your default database client postgres
? Database name: strapi
? Host: 127.0.0.1
? Port: 5432
? Username: strapi
? Password: ******
? Enable SSL connection: No

Authenticating

https://strapi.io/documentation/v3.x/guides/api-token.html#introduction

NOTE: strapi handles users and administrators separately. Users will have access to your client side, where as administrators have access to the strapi-based backend as well. Administrators are users, but user's are not necessarily adminstrators.

Users are basically just a collection-type in strapi, that have some default permissions and roles applied for us out of the box. Users can be managed like any other collection-type, with all basic CRUD functionality available out of the box.

Users can also be blocked from the strapi admin panel, so if you ever need to revoke a user's access this can be done from the Blocked setting on the user's profile in the admin panel

Default Auth for Administrators:

Login

POST ||  "\auth\login"                          => {token, user}

// request.json

{
  "identifier": "you@youremail.com",
  "password": "yourpassword"
}

Registration

POST ||  "\auth\login\register"         => {token, user}

// request.js

{
  "username": "yourusername",
  "email": "you@youremail.com",
  "password": "yourpassword"
}

JWT Access Token

In order to make authenticated requests, we'll need to grab the authToken that is returned from either the login or the registration endpoints and use that in order to populate our authorization header to send alongside our requests
{
 "Authorization": "Bearer <accessToken>"
}
Authenticated routes that do no have an authorization header or ones that provide invalid tokens, will fail with a 403 forbidden error.

Access Authenticated Routes

GET || http://localhost:1337/articles

POST || http://localhost:1337/articles

{
  "user": 1,
  "title": "This is the title of my article",
  "content": "This is some authenticated request content"
}

Current User

We can also determine the user details of the current user, by hitting a specific endpoint generated by strapi:

GET || http://localhost:1337/users/me           => {user}

Authentication Providers

Strapi provides several built-in authentication provider profiles, that we can simply generate an api key for. As an example we'll take a quick look at how to setup google as a strapi authentication provider.

NOTE: In order to use third party auth providers our strapi backend must be available to the web. For local development installations we can simply just use ngrok to provide us with an ssh tunnel that will expose our local environment for us.

./ngrok http 1337

This will spin up a local ngrok tunnel for our strapi application which is running on port 1337

ngrok by @inconshreveable                                                                                                                                        (Ctrl+C to quit)

Session Status                online                                                                                                                                             
Account                       Gaurang Shah (Plan: Free)                                                                                                                          
Version                       2.3.35                                                                                                                                             
Region                        United States (us)                                                                                                                                 
Web Interface                 http://127.0.0.1:4040                                                                                                                              
Forwarding                    http://6eb63f1d736e.ngrok.io -> http://localhost:1337                                                                                              
Forwarding                    https://6eb63f1d736e.ngrok.io -> http://localhost:1337                                                                                             

Connections                   ttl     opn     rt1     rt5     p50     p90                                                                                                        
                              0       0       0.00    0.00    0.00    0.00

Now if we were to navigate to: http://6eb63f1d736e.ngrok.io we will be able to access our local strapi install while ngrok is running.

Setup Google Authentication

https://console.developers.google.com

[ ] Register a new project with google console
- (click new project from project list dialog at the top)
[ ] Define project name (will be used to identify your project in google's console)
[ ] Setup OAuth Consent Screen (External = Open to Public Signup)
- [ ] Add an application name
- [ ] ⚠️ DO NOT add an application logo (this triggers google's approval process, we can avoid that by leaving it blank)
- [ ] Add "Authorized Domains" (ngrok link w/ no protocol or trailing slash)
```
6eb63f1d736e.ngrok.io
```
- [ ] NOTE: Add links to homepage, privacy policy, and terms of service
- [ ] SAVE
[ ] Generate OAuth Credentials
- [ ] Click Create Credentials
- [ ] Select OAuth Client ID
- [ ] set Application Type : web application
- [ ] assign a name (use the same as the project -- keep it simple)
- [ ] Authorized Javascript Origins: (no trailing slash)
```
https://6eb63f1d736e.ngrok.io
```
- [ ] Authorized redirect URIs
```
http://6eb63f1d736e.ngrok.io/connect/google/callback
```
⚠️ NOTE must use http with local ngrok tunnel

callback used by google when a authentication request is triggered
- [ ] SAVE
[ ] Save Credentials to Notes (Client ID, Client Secret)

Client ID : 426492773429-f91fhpg1l820clhrfoge5cb59lnh0t27.apps.googleusercontent.com

Client Secret: sbh5eD4eydVjKMMkReU7Ss8K

Configure Strapi Google Auth Credentials

[ ] Enable Google as a provider
[ ] Add Client ID
[ ] Add Client Secret
[ ] prefix the redirectURL with our ngrok tunnel address

Connect To Google OAuth

http://6eb63f1d736e.ngrok.io/connect/google

☝️ NOTE: When we navigate to the address above we get an 400 invalid_request error. This is because, Strapi uses a custom parameter called: strapi.config.server.url to determine the correct url where strapi is currently being served from.

Since we're running an ngrok tunnel strapi doesn't recognize that it is being tunneled into and so we get the invalid_request error, because the parameter never got set since we tunneled in.

To fix this we'll need to update our server settings and add the ngrok url so that strapi is aware of it:
// config/server.js

module.exports = ({env}) => ({
  /* ... */
  url: "http://6eb63f1d736e.ngrok.io",
  /* ... */
})
NOTE: be sure to leave off the trailing slash on the url

Now your changes should be reflected in your strapi console, when strapi restarts:
 Project information                                                          

┌────────────────────┬──────────────────────────────────────────────────┐
│ Time               │ Mon Nov 02 2020 15:16:26 GMT-0500 (Eastern Stan… │
│ Launched in        │ 4480 ms                                          │
│ Environment        │ development                                      │
│ Process PID        │ 22312                                            │
│ Version            │ 3.2.4 (node v14.0.0)                             │
│ Edition            │ Community                                        │
└────────────────────┴──────────────────────────────────────────────────┘

 Actions available                                                            

Welcome back!
To manage your project 🚀, go to the administration panel at:
http://6eb63f1d736e.ngrok.io/admin

To access the server ⚡️, go to:
http://6eb63f1d736e.ngrok.io
As we can see the url to our strapi installation now shows our ngrok url instead, so now we can try to connect to google's OAuth again:

Upon successful authentication we get a response with a token and information associated with the google user account.

NOTE: if user tries to use an email that is already registered thru another provider (i.e., strapi's built-in email provider) you will see another 400 error :
{"statusCode":400,"error":"Bad Request","message":[{"messages":[{"id":"Auth.form.error.email.taken"}]}],"data":[{"messages":[{"id":"Auth.form.error.email.taken"}]}]}
This is because the email already matches an existing user.

Now that we've successfully setup a 3rd party OAuth provider, we can now utitlize the token and information google provides back to us in our application. In order to do that we'll need to update our callback url, that we set in strapi and point to the url of the application where we want to consume this from:

WIth this in place you'll be able to make a GET request to the following endpoing from your application once a user has logged in to get their user details and jwt token from strapi:

GET || `${STRAPI_API_URL}/auth/google/callback?access_token=${access_token}`

https://6eb63f1d736e.ngrok.io/auth/google/callback/?access_token=eylkjadfoi2490r8290riapojf09i.aowj23r90uiap023ir9fakm049urf.092u4t90ue09tu2jt4u9jg0u9

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MTYsImlhdCI6MTYwNDM1MDU3NywiZXhwIjoxNjA2OTQyNTc3fQ.sPODgmc89FTTf33lt4N6sNURaIivI2otQeO5Nuu2fKQ

Creating Email Service

[ ] Install NodeMailer as Email Provider:

  npm i strapi-provider-email-nodemailer-v3

other email providers

strapi-docs

Configure Nodemailer as as strapi provider

// config/plugins.js

module.exports = ({ env }) => ({
  email: {
    provider: "nodemailer-v3",
    providerOptions: {},
    settings: {
      host: "process.env.SMTP_HOST",  
      port: 587,
      username: "process.env.EMAIL_ADDRESS",
      password: "process.env.EMAIL_PASSWORD",
      secure: false, // docs suggest keeping this as false when using port 587
    },
  },
})

be sure to grab the config from your test email account, or use: https://ethereal.email

npx strapi generate:service <servicename>

npx strapi generate:service email

This will create the following folder structure:

api
├── email
│   ├── documentation
│   └── services

And this is the one file the command generates.

// api/email/services/email.js

'use strict';

/**
 * `email` service.
 */

module.exports = {
  // exampleService: (arg1, arg2) => {
  //   return isUserOnline(arg1, arg2);
  // }
};

we'll update the service with our own logic

module.exports = {
  sendEmail: async(to, subject, html) => {
    // ☝️ creates logs for each email sent that show in the console
    strapi.log.info("sendEmail: Sending Email")
    console.log('hello')
    // ☝️ references the built-in email plugin to envoke it's send(fn)
    await strapi.plugins["email"].services.email.send({
      // the basic configuration required by strapi's built-in email plugin
      to,
      from: process.env.EMAIL_ADDRESS,
      replyTo: process.env.EMAIL_ADDRESS,
      subject,
      html,
    })
    strapi.log.info("sendEmail: Email Sent")
  }
};

Set up Cron task for testing email implementation:

Next thing we'll need to do is enable strapi's cron task feature through our server, this will simply allow us to setup a cron job to test that the server is able to send emails
// config/server.js

module.exports = ({ env }) => ({
  host: env("HOST", "0.0.0.0"),
  port: env.int("PORT", 1337),

  cron: { enabled: true }, // enables all cron tasks

  admin: {
    auth: {
      secret: env("ADMIN_JWT_SECRET", "1f2afe006aac41e4ed791f66babcc874"),
    },
    host: "0.0.0.0",
    port: 3000, // --watch-admin
  },
});
Now we can setup our cron task:
  '0 * * * * *': async () => {
    return await strapi.services.email.sendEmail(
      process.env.EMAIL_ADDRESS,
      "Test Subject Line",
      "<div class"test">Test Context</div>" // include string or html
    )
  }
*❗️ NOTE: * the asterisks mean that this task will run every second. to stop the task use the commented setting. Specifying 0seconds means it will run once every minute instead. (basically when the seconds reset back to zero after 0:59).

Policies

Policies are functions which have the ability to execute specific logic on each request before it reaches the controller's action. They are mostly used for securing business logic easily. Each route of the project can be associated to an array of policies

For example, you can create a policy named isAdmin, which obviously checks that the request is sent by an admin user, and use it for critical routes.

If you enjoyed my content, please feel free to connect with me wherever you spend your time online.

Are you an absolute beginner programmer? You might be in the best place possible.

gshah2020 — Wed, 29 Aug 2018 15:41:30 +0000

There are a few very simple reasons why newbies, might be in the best place possible in the modern coding landscape. Given it's probably easier to learn how to program now, than it has ever been in history.

Although, this hypothesis is based purely on the fact that, you're not set in your ways, you haven't adopted tons of different ideologies. In short, you're not a fan-boy/girl...yet...

The sad truth (and eventual reality) is, pretty soon you will be! All of the cliches are completely true. I didn't think it could happen to me, but it inevitably did. So, this is my attempt to steer you towards the light before its too late for you too.

-- Message from the DarkSide ;)

(UPDATE: see first comment, this will be you soon).

First thing you'll probably do is go on the hunt for a code editor or IDE (integrated development environment). Some people prefer heavy duty IDE's capable of handling anything and everything you throw at it.

Other people may actually gravitate to simpler tools, with wysiwyg editors that allow you to write HTML5 / Markdown, many of these are found all over the web.

As with all tools, if you use a hammer, and it's your hammer, you'll eventually become fond of it. It's not that your hammer is better than every other hammer, ever made before. It's just that your hammer has helped to achieve so much. It is like a weapon in your arsenal...a trusted tool and we all know how hard trust can be to earn. So you and your hammer share a unique relationship. It works for you and with you. In fact it may even feel like it makes you better at what you do.

This is true for just about any tool, and even most everyday objects. So how does this apply to coding?

Well, your IDE is your hammer!

(All these hammer references, and not a single Norse-god pun, I must be slipping these days). Not to worry...

Actually, your IDE will eventually feel more like Batman's tool belt rather than Thor's hammer. It's packed full of stuff, most of it you'll never use. But a few awesome tricks, tools, and maybe even some magic here and there, because programmers seem to have a taste for theatrics, kind of like Batman, as well.

Many developers will be more than happy to tell you what IDE they use, and why it's better than any other. Just like anyone who's gone into war with their hammer, and come out on top time and time again, they may even write legends about said hammer, depending on how good you in fact were with it.

Also, how crazy do you have to be to go to war with a hammer? Just like those Norse legends though, let's leave that for later generations to write about.

In the here and now, your IDE is your hammer/tool belt, you won't want to leave home without it.

So the topic of picking your first IDE is an important one, and most fail to really explore their options. Don't think Thor has ever had to use a sword? Even he recently was forced to trade in the hammer for a massive pick axe.

So yes, while it's not about the tool, the point is that the right tool makes the process a whole lot more enjoyable and hopefully...productive.

Picking the right tool is about trying a few things until something just feels right for you. So have some fun, make some cool stuff, and hammer around a bit till it feels right.

Here's a list of the top IDE's one the market. None is like the other. They all may share traits, others may build in a ton of features. Some are proprietary and others are open-source. Simply put they vary, like everything else in the programming world.

https://www.infoworld.com/article/3217008/development-tools/the-most-popular-ides-visual-studio-and-eclipse.html

The moral of this story is, if you're going to war, you may want to try out a few swings with a sword, or even a pick axe. Who knows when you'll need one, and you're probably better off informed and experienced, no matter how much you love your hammer.

Choose wisely my friends.

See the bottom of this post for more on my personal hammer.

Microsoft Visual Studio
Eclipse
Android Studio
vim
NetBeans
JetBrains IntelliJ
Xcode
Komodo
Sublime Text 3
Xammarin

Number 11 on this list is actually my favorite IDE of them all. Microsoft's Visual Studio Code. Initially released in 2015, it's one of the latest and greatest editors on the market.

**Not to be confused with "Visual Studio".

Visual Studio Code was built from the ground-up as a light-weight IDE that kind of skates the very thin line between IDE and code-editor using the open-source Monaco Editor, built on top Google's Chrome Browser, in an Electron wrapper.

With support for just about every language, built on standard open-source front-end technologies. Visual Studio Code is a blazing-fast light-weight IDE that is highly configurable which gives you the ability to solve one of the biggest issues with switching from one IDE to the next...keyboard shortcuts.

Visual Studio code will import your shortcuts from just about every other IDE in the market, with a strong focus on converting Sublime and Atom users. As it does really solve the problems that both those users face currently in each of those editors! And they do it well!

Really well, with thousands of extensions solving problems like local server, automatic refresh, and probably the biggest one of them all...Emmett built-in. Which really makes this editor literally complete right out of the box.

Hope you'll let me know your thoughts, and I really hope you found some great insight in our round-up of the most popular IDE's and why they're similar to a legendary hammer in your repertoire.

P.s. I’m not the only die-hard advocate, with growing appreciation, more and more developers are embracing the difference...

https://blog.bitsrc.io/a-convincing-case-for-visual-studio-code-c5bcc18e1693

Happy Hammering :)

If you enjoyed my content, please feel free to connect with me wherever you spend your time online.