DEV Community: Justin Boyson

Streamline your Vue 3 development with Fauna, Typescript, and GraphQL

Justin Boyson — Tue, 27 Apr 2021 23:24:26 +0000

Written in connection with the Write with Fauna Program.

Photo by Srinivasan Venkataraman on Unsplash

GraphQL is amazing, but writing reducers and setting up the server side can be a bit daunting. Thankfully Fauna can do the heavy lifting and let us focus on the fun stuff!

To take it up a notch let’s sync up our GraphQL types with a code generator so that we can leverage Typescript and and VSCode’s intellisense for a seamless coding experience.

To demonstrate we will be building a simple orders list.

Overview

Set up a vite app
Build a static version of order list
Build our schema and upload to Fauna
Use codegen to create types for our schema
Wire up the static list to live data
Bonus: Updating schema workflow

We’ll be using yarn, and vite for this project but you could just as easily use Vue CLI if you prefer and npm. Also if react is more your cup of coffee, most of this will still be applicable.

Set up a vite app

Setting up vite is delightfully easy. Simply run yarn create @vitejs/app in your terminal and follow the prompts. I called mine “fauna-order-list” and chose the “vue-ts” template. Then cd into your directory and run yarn

That’s it!

Go ahead and run your app with yarn dev

Behold the mighty Vue starter template!

Build a static version of order list

For quick styling we’ll be using tailwind. The tailwind documentation is great so go here and follow their instructions.

Note: if you have the dev server running still you will need to restart the process to see tailwind’s styles.

Next create a new file src/components/OrderList.vue and paste in the following code:

<template>
  <div class="shadow overflow-hidden border-b border-gray-200 sm:rounded-lg">
    <table class="min-w-full divide-y divide-gray-200">
      <thead class="bg-gray-50">
        <tr>
          <th scope="col" class="order-header">Name</th>
          <th scope="col" class="order-header">Address</th>
          <th scope="col" class="order-header">Order</th>
          <th scope="col" class="order-header">Total</th>
        </tr>
      </thead>
      <tbody>
        <tr class="bg-white">
          <td class="order-cell">
            <span class="bold">Jane Cooper</span>
          </td>
          <td class="order-cell">123 Main St, New York, NY 12345</td>
          <td class="order-cell">12oz Honduras x 1</td>
          <td class="order-cell">$12.00</td>
        </tr>
        <tr class="bg-gray-50">
          <td class="order-cell">
            <span class="bold">Bob Smith</span>
          </td>
          <td class="order-cell">456 Avenue G, New York, NY 12345</td>
          <td class="order-cell">12oz Honduras x 1, 12oz Ethiopia x 2</td>
          <td class="order-cell">$36.00</td>
        </tr>
      </tbody>
    </table>
  </div>
</template>

<style>
.order-cell {
  @apply px-6 py-4 whitespace-nowrap text-sm text-gray-500;
}

.order-header {
  @apply px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider;
}

.bold {
  @apply font-medium text-gray-900;
}
</style>

Now we need to add the OrderList component to our app.

Open up src/App.vue and replace all occurrences of HelloWorld with OrderList. While we’re in here let’s delete the style section and image as well. I’ve also wrapped OrderList in a section and added a couple styles to center and pad the list.

Your completed App.vue file should look like this.

<template>
  <section class="container mx-auto mt-8">
    <OrderList />
  </section>
</template>

<script lang="ts">
import { defineComponent } from "vue";
import OrderList from "./components/OrderList.vue";

export default defineComponent({
  name: "App",
  components: {
    OrderList,
  },
});
</script>

Build our schema and upload to Fauna

A basic schema

For our example data we will have two primary data objects. Customers and Orders.

Customers will have a name and address. Orders will have an array of LineItems and a reference to a Customer

Our basic schema looks like this:

type Address {
  line1: String!
  line2: String
  city: String!
  state: String!
  postal_code: String!
}

type Customer {
  name: String!
  address: Address
}

type LineItem {
  name: String!
  amount: Int!
  quantity: Int!
}

type Order {
  items: [LineItem!]!
  customer: Customer!
}

Here we can see an Address type that could be used to store information like you might gather from a checkout form. Likewise, we have a LineItem type to hold individual items for a given order.

Fauna specific directives

Fauna comes with several directives to help auto generate resolvers for your schema. They’re powerful and well worth your time to read through the documentation. In this tutorial we will be covering two of them: @collection and @embedded.

In Fauna, all types in a graphql schema are considered @collection by default. If you are coming from a relational database background you can think of collections as being similar to tables.

I prefer to explicitly name my collections using the @collection directive to remove any ambiguity, and because I am finicky about my document names 😁

The @collection directive takes one simple argument: “name” which is what Fauna will call the document for this collection.

Looking at our current schema we only want customers and orders collections. To prevent Address and LineItem from becoming documents we use the @embedded directive. This simply tells Fauna to not create separate collections for these types. These types are “embedded” directly in whatever other type references them.

Our final schema should now look like this:

type Address @embedded {
  line1: String!
  line2: String
  city: String!
  state: String!
  postal_code: String!
}

type Customer @collection(name: "customers") {
  name: String!
  address: Address
  orders: [Order!] @relation
}

type LineItem @embedded {
  name: String!
  total: Int!
  quantity: Int!
}

type Order @collection(name: "orders") {
  items: [LineItem!]!
  customer: Customer!
}

Save this to src/graphql/schema.graphql

Upload to Fauna

Navigate to https://dashboard.fauna.com and create a new database. I called my “fauna-order-list”, the same as my vite app. Then select “GraphQL'' from the left sidebar.

Click the import button and select schema.graphql

After a few moments you should have the GraphQL Playground open.

Add some data

The GraphQL Playground is actually pretty handy for creating test data. We won’t cover updating information from the app in this tutorial, but generally when writing queries I write and execute them in the GraphQL Playground first. Then copy and paste those queries as string constants locally. This way I know that my queries are correct.

Create a customer

Since our orders need a customer to reference, let’s start by creating a customer.

Fauna has already generated create mutations for both orders and customers. You can see this in the very helpful auto-completions in the playground. If you have never used a GraphQL playground before you can see what is available at any time by opening up the “DOCS” tab on the right hand side of the window.

Your query should look like this at this point:

mutation {
  createCustomer
}

Note how there is a red indicator to the left of line 2. If you hover over “createCustomer” you will get a helpful popover with error information. In this case it is asking for subfields to return, and saying that a “CustomerInput!” is required.

For our purposes we just need the "_id". And for the CustomerInput we’re going to use a variable, so we add a variable reference as well.

Our final mutation looks like this, and our error messages have all been resolved:

mutation ($data: CustomerInput!) {
  createCustomer(data: $data) {
    _id
  }
}

Now to provide a value for $data at the bottom of the tab you will find “QUERY VARIABLES” and “HTTP HEADERS”

Click “QUERY VARIABLES”. You can also drag the variables tab up to create more room.

Inside the variables tab we have the same auto-complete functionality as above. You can ctrl+space to see what options are available, or just start typing if you already know what you need.

Here you will see. that since createCustomer needs a data parameter, that is what auto-complete will recommend. Also notice as you add properties, the error hints that show up. These will all guide you toward providing correctly formatted data as per your schema.

Once you have your variable filled out, click the play button to see your result. Since we only asked for _id to be returned that is what you should see in the result tab.

Here is my final variable for reference:

{
  "data": {
    "name": "John Smith",
    "address": {
      "line1": "123 Main St",
      "city": "Austin",
      "state": "TX",
      "postal_code": "12345"
    }
  }
}

Create an order

Since orders need a customer reference we’re going to leave this tab open and start a new tab for the orders. Click the + tab right next to the createCustomer tab. As a quick aside, notice how the tabs are helpfully named after the query that is being run and that the type of query is labeled as well. In this case, “M” for mutation.

The createOrder mutation follows the same process as before. The interesting part here is how we connect customers to orders. Take a look at the final variable here:

{
  "data": {
    "customer": {
      "connect": "294049263884698114"
    },
    "items": [
      {
        "name": "12oz Honduras",
        "total": 1200,
        "quantity": 1
      }
    ]
  }
}

That connect parameter is what “links” an order to a customer. In the auto-complete when writing this variable you may have noticed another option, create.

This is one of the really cool and powerful things about GraphQL. This kind of flexibility allows us to create a customer and an order at the same time, while simultaneously linking them together. And Fauna took care of all the resolvers for us, so we get all of this functionality for free! 😍

Here is an example variable parameter to use with createOrder that does all of the above:

{
  "data": {
    "items": [
      {
        "name": "12oz Ethiopia",
        "quantity": 1,
        "total": 1200
      }
    ],
    "customer": {
      "create": {
        "name": "Jane Doe",
        "address": {
          "line1": "456 Ave A",
          "city": "New York",
          "state": "NY",
          "postal_code": "11111"
        }
      }
    }
  }
}

Listing the orders

Now that we have some test data let’s open another GraphQL Playground tab and write the select query. Using ctrl+space you should notice something missing. Currently it looks like we can only “findByCustomerID'' and “findByOrderID” 🤔

At the time of this writing we need to explicitly create an @index to display our Orders.

In plain GraphQL we are simply defining a Query. Since we want to return “all orders” let’s call this one allOrders. This will be an array of Orders and we want to insist that it return something so our basic GraphQL query looks like this:

type Query {
  allOrders: [Order!]!
}

And to define the index we simply add an @index directive with a name so our final query looks like this:

type Query {
  allOrders: [Order!]! @index(name: "all_orders")
}

We add this to our schema.graphql file, then back in GraphQL Playground select “UPDATE SCHEMA” from the top of the screen and upload our updated schema.

After a brief moment the schema is updated and we have our allOrders query available like so:

{
  allOrders {
    data {
      _id
      customer {
        name
        address {
          line1
          line2
          city
          state
          postal_code
        }
      }
      items {
        name
        total
        quantity
      }
    }
  }
}

Execute this query in the playground and we see our two orders! Awesome.

Notice the nested data object. This is because there are three top level properties to the return object when querying GraphQL. data holds the data for the current result set. before and after hold cursors for paginating the results. We will not go over pagination in this tutorial, but it’s good to remember that when extracting this information later that you need to reference data since the array is not available at the top level.

Now that we have a working query let’s save it locally for use later in our app. Save this query to src/graphql/queries.ts like this:

export const allOrders = `
{
  allOrders {
    data {
      _id
      customer {
        name
        address {
          line1
          line2
          city
          state
          postal_code
        }
      }
      items {
        name
        total
        quantity
      }
    }
  }
}`;

Use codegen to create types for our schema

Now that our data is ready to go, let's set up codegen to generate types for us to use in our app.

For detailed instructions follow the documentation here. The quick version is listed below.

Execute the following commands:

yarn add graphql
yarn add -D @graphql-codegen/cli @graphql-codegen/typescript
yarn graphql-codegen init

Here are the responses I used for the prompts:

Now if you try running yarn codegen you will get an error. 😱

We need to provide an authorization header to connect to Fauna.

Add authorization header

Go to the Fauna dashboard for this database and select “Security” from the left side menu
Click the “NEW KEY” button
Choose “Server” for the role and save
Copy the key’s secret to your clipboard
Create a .env file in you app’s root directory
Save the key’s secret to .env like so: VITE_FAUNA_KEY=PASTE_HERE
In package.json update the codegen script by adding “-r dotenv/config” so that it looks like this: "codegen": "graphql-codegen --config codegen.yml -r dotenv/config"

Open codegen.yml and add the Authorization header, and remove the “documents” key like so:

overwrite: true

  schema:
    - https://graphql.fauna.com/graphql:
        headers:
          Authorization: Bearer ${VITE_FAUNA_KEY}
  generates:
    src/schema.d.ts:
      plugins:
        - "typescript"

Try running yarn codegen again. Hooray 🎉

Go take a look at schema.d.ts and see all the typing you just saved. It’s not important to understand every line that was created here. Just that these types will help ensure that we correctly format our GraphQL queries correctly, and that our data structures locally are in sync with the server.

Some notes on security and best practices

We are using Vites’ built in dotenv functionality to easily store our secret key locally, but in a real application you should never do this. The reason is that when we use the secret key later in our app Vite will actually include it in the bundled code which means anyone picking through your source could see it.

In a real application this would be stored in an environment variable on a server and you would access that api instead of hitting Fauna directly. This is beyond the scope of this tutorial, just know that you should never include secret keys in a repository, or expose them publicly.

Wire up the static list to live data

Finally we get to pull it all together.

Use Suspense to display async components

First open up App.vue and wrap OrderList in a Suspense tag to prepare for rendering components with async data

<Suspense>
  <OrderList />
</Suspense>

Use fetch to retrieve the orders

For simplicity we’re going to just use fetch to natively retrieve the orders.

Open OrderList.vue and add a script tag using typescript and the setup option <script lang="ts" setup> Note that setup is still in RFC so it may not make it into the final version of Vue 3. But it has a ton of support from the community and is most likely stable at this point. I believe it greatly reduces unnecessary boilerplate and makes for a better development experience so I’m using it in these examples.

Also note that we’ll be using Vue 3’s composition API.

Thinking through our data, the first thing we’ll need is a ref to an array to hold the orders. Then we’ll await a fetch post to Fauna and store the data in orders.value

import { ref } from "vue";
import { allOrders } from "../graphql/queries";
import type { Order } from "../schema";

const orders = ref<Order[]>([]);
orders.value = await fetch("https://graphql.fauna.com/graphql", {
  method: "POST",
  body: JSON.stringify({ query: allOrders }),
  headers: {
    Authorization: `Bearer ${import.meta.env.VITE_FAUNA_KEY}`,
  },
})
  .then((res) => res.json())
  .then(({ data }) => data.allOrders.data);

Run the dev server yarn dev and open up the app in your browser. Using vue-devtools inspect the OrderList component and see that it now has an orders property under setup populated with our data. Neat!

Prepare the data for easier display

We’ll use a computed value to map the orders array into an easier to consume format. For example, customer.address is currently an object as you might expect it to be stored. But we just want a string to display in the table, so we will use map to create a new parsedOrders array formatted how we want it.

const parsedOrders = computed(() => {
  return orders.value.map((o) => ({
    _id: o._id,
    name: o.customer.name,
    address: `${o.customer.address?.line1} ${o.customer.address?.city}, ${o.customer.address?.state} ${o.customer.address?.postal_code}`,
    items: o.items.map((i) => `${i.name} x ${i.quantity}`).join(", "),
    total: new Intl.NumberFormat("en-US", {
      style: "currency",
      currency: "USD",
    }).format(o.items.reduce((pre, cur) => pre + cur.total, 0) / 100),
  }));
});

Thanks to our generated schema types our IDE gives us helpful autocomplete for our deeply nested objects such as o.customer.address?.line1 and even knows to safely check that nullable fields are available.

Now we just swap out our static HTML for our parsedOrders data:

<tr
    v-for="(order, index) in parsedOrders"
    :key="order._id"
    :class="{ 'bg-gray-50': index % 2 !== 0 }"
    class="bg-white"
    >
  <td class="order-cell">
    <span class="bold">{{ order.name }}</span>
  </td>
  <td class="order-cell">{{ order.address }}</td>
  <td class="order-cell">{{ order.items }}</td>
  <td class="order-cell">{{ order.total }}</td>
</tr>

Our final OrderList component should look like this:

<template>
  <div class="shadow overflow-hidden border-b border-gray-200 sm:rounded-lg">
    <table class="min-w-full divide-y divide-gray-200">
      <thead class="bg-gray-50">
        <tr>
          <th scope="col" class="order-header">Name</th>
          <th scope="col" class="order-header">Address</th>
          <th scope="col" class="order-header">Order</th>
          <th scope="col" class="order-header">Total</th>
        </tr>
      </thead>
      <tbody>
        <tr
          v-for="(order, index) in parsedOrders"
          :key="order._id"
          :class="{ 'bg-gray-50': index % 2 !== 0 }"
          class="bg-white"
        >
          <td class="order-cell">
            <span class="bold">{{ order.name }}</span>
          </td>
          <td class="order-cell">{{ order.address }}</td>
          <td class="order-cell">{{ order.items }}</td>
          <td class="order-cell">{{ order.total }}</td>
        </tr>
      </tbody>
    </table>
  </div>
</template>

<script lang="ts" setup>
import { ref, computed } from "vue";
import { allOrders } from "../graphql/queries";
import type { Order } from "../schema";

const orders = ref<Order[]>([]);
orders.value = await fetch("https://graphql.fauna.com/graphql", {
  method: "POST",
  body: JSON.stringify({ query: allOrders }),
  headers: {
    Authorization: `Bearer ${import.meta.env.VITE_FAUNA_KEY}`,
  },
})
  .then((res) => res.json())
  .then(({ data }) => data.allOrders.data);

const parsedOrders = computed(() => {
  return orders.value.map((o) => ({
    _id: o._id,
    name: o.customer.name,
    address: `${o.customer.address?.line1} ${o.customer.address?.city}, ${o.customer.address?.state} ${o.customer.address?.postal_code}`,
    items: o.items.map((i) => `${i.name} x ${i.quantity}`).join(", "),
    total: new Intl.NumberFormat("en-US", {
      style: "currency",
      currency: "USD",
    }).format(o.items.reduce((pre, cur) => pre + cur.total, 0) / 100),
  }));
});
</script>

<style>
.order-cell {
  @apply px-6 py-4 whitespace-nowrap text-sm text-gray-500;
}

.order-header {
  @apply px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider;
}

.bold {
  @apply font-medium text-gray-900;
}
</style>

Bonus: Updating schema workflow

Most of our schema’s evolve over time as new requirements come in. Let’s walk through a very simple schema update and how we would update our app to accommodate.

In this example let’s say we now want to collect email addresses. First we add email to our schema.graphql

type Customer @collection(name: "customers") {
  name: String!
  address: Address
  email: String
  orders: [Order!] @relation
}

Note: for simplicity’s sake I am leaving email as not required. If we made email required like this email: String! then we would also have to write a data migration script to update all the existing documents, because our allOrders query would now fail.

Now that our schema is updated locally, we update the schema in Fauna’s dashboard just as we did before by going to the GraphQL tab, clicking “UPDATE SCHEMA” and uploading our updated schema file.

While we’re in the dashboard let’s go ahead and update a customer to have an email address. I found this easiest to do by going to the Collections tab and editing a document directly. Pick your first customer and add an email field.

Go back to the GraphQL tab and select the allOrders tab. Add email to your query under customer and you should now see emails being returned.

Copy and paste this query back into queries.ts and now we should be ready to display emails in our app.

Run yarn codegen to sync up with Fauna

Open up OrderList.vue and add email to the parsedOrders computed variable.

Then simply display order.email next to the customer’s name. Note, you might have to refresh the page to get the schema updates to take effect.

That’s it!

Conclusion

I’ve been really enjoying using Fauna’s GraphQL endpoint. It has greatly streamlined my process for development. Considering it is still in early stages it’s only going to get better from here, which is pretty incredible.

State of CSS: Multi-Column Layout

Justin Boyson — Thu, 21 Jan 2021 04:43:55 +0000

Photo by Daniel Cheung on Unsplash

The State of CSS 2020 came out recently. Reading through it I realized that I have some pretty big gaps in my CSS knowledge. What better way to plug that gap than a series on all things CSS that I missed?

I'm going to walk through all the features in State of CSS. I'll cover topics that are either new to me, or less than half of respondents say they have used.

Let's kick it off with Multi-Column Layouts!

First an example: view on codepen

I alway forget about this one, but it's super handy. You don't always need CSS Grid. Sometimes you just want your beautiful prose not to spread across the screen like a rude subway passenger.

The syntax is short and easy to understand.

column-count

If you want a fixed number of columns.

column-width

The real money maker. Auto generate columns of a certain size OR character count.

column-rule

Style the dividing line between columns.

column-gap

Set the space between columns.

column-span

Make an element span all columns. User for fancy headings or ad banners (please don't use it for ad banners).

That's it for now, next time we'll cover position sticky!

You > You Think

Justin Boyson — Tue, 21 Jul 2020 18:59:58 +0000

A co-worker replied to this tweet:

// Detect dark theme var iframe = document.getElementById('tweet-1285491488433082374-222'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1285491488433082374&theme=dark" }

It's a great question, and when I went to respond I had way more than the allotted character count to say about it.

You see, present day me works for a company that I am very proud to work for doing work that I am very proud of doing. I am compensated well, and my boss is amazing.

But this wasn't always the case. And I spent way too long working terrible jobs while my career stagnated.

It is my sincerest hope that this post might help someone lift themselves up and demand better.

Here is my journey so far, including the turning point that doubled my salary and made me fall in love with web development again.

A dubious beginning

I was 19 years old working two jobs as a grocery store bagger and a busboy at a barbecue place, when I found out I was going to become a father.

Panic set in immediately. I could barely pay rent and feed myself let alone care for a tiny human.

After brainstorming/crying/hyperventilating alone in my room I remembered how much fun I had playing with my old Commodore-64 back in the day. Couple that with this new "World Wide Web" thing that kept showing up in the news (this was 1997) and a thought started to form.

How can a kid with no experience and no education gain meaningful employment?

💡 Get good at something nobody else is good at!

I was fortunate enough to recognize that this internet thing would have some opportunity so I bought myself an "HTML for Dummies" book and got to work building websites using notepad on my old beat up Windows machine.

Fast forward a couple years and I got my first real programming job working for a Y2K company that was trying to branch out. They literally asked for someone they could "pay nothing and treat like garbage".

And that dear readers basically defined the next 15 years of my "career".

Carrying a ton of baggage on the road to Struggle City

I spent about a year at that first job and found my way to hot ".com" that paid me really well considering I had no education and very little experience.

I loved it there, but the .com bubble burst shortly after 9/11 and I found myself unemployed for 9 months. I lost everything. I burned through my savings, cashed in my tiny 401k, got my car repossessed and sold everything I had of value. I ended up sleeping on the couch of a friend of a friend with some clothes in a trash bag as my only possessions.

I eventually got a pity job for half what I was making before and then lost that when Dell off-shored all of their contractors sending me back to square 0 again.

Welcome to Struggle City: Population Me

By this point I had a full blown case of impostor syndrome. Multiple layoffs and years struggling through one "Office Space" company after another left me feeling defeated and small. I was so broke and desperate that I never made a "career choice" but just took the first job that said yes to me.

Please like me.

Around this time I picked up a part-time contract gig that helped me limp along in-between jobs. At some point it became busy enough that they wanted to hire on a full time employee.

So they asked someone else. 😢

But he said no, so they settled for me. 😬

If that doesn't set you up for failure I don't know what will.

Regardless, I threw myself in determined to do a good job. And I did do a good job. I worked my tail off for seven years and never got a raise.

Read that again. Seven years. No raise.

And I still like felt like a worthless jerk for taking their money even though I did everything for that company. And when I say I did everything I mean I did everything.

I was fullstack before that was even a term. 😉

Here's a quick rundown of what I did there so that you can understand how deep impostor syndrome can run:

I installed the OS onto bare metal servers and put them in the rack.
I designed the database schema from scratch and installed the database server to run it.
I built the APIs to interface with that database as well as data transformations to ingest and export customer data.
I installed and configured the webservers.
I set up all of the above in multiple environments for dev, staging, and prod.
I then coded up all the websites that I also designed.

ALL. BY. MY. SELF.

And when we had to move off of Microsoft solutions to save money I migrated us off of our custom system to an open-source Linux based solution in less than two months.

That means I learned: Linux, PHP, and MySql good enough to stand up multiple production websites from bare metal in LESS THAN TWO MONTHS. And they ACTUALLY WORKED.

I look at this list now and see a rock star. But back then I only saw all the mistakes I made. I hadn't had a raise in seven years and I felt like I didn't deserve one.

A quick aside before anyone demonizes the company. I don't blame them. This was all on me. They were struggling to survive the whole time and didn't have the expertise to even know that I was doing a good job. So as far as they knew, I wasn't doing a good job.

It is my job to make sure that my successes and struggles are being communicated.

The turning point

I had built the websites off of Drupal and as luck would have it DrupalCon was coming to Austin. So I made a point to get a ticket and go learn what I could.

I had spent the last few years consuming resources from certain companies and authors. I had put all these people up on pedestals. I thought to myself "that's what a real developer looks like". And I never saw myself as a peer to these people, but as just some rando struggling to get by.

After all the talks I met up with a couple people I had met on Twitter and we went to dinner with some of the speakers.

That dinner changed my life. I got to have long conversations with people who were miles ahead of me in my mind and found out they were all *gasp* regular humans!

Sure all of them were better than me at something, but some of them had never even heard of some of the things I was very good at.

Talking database schemas with one speaker, and DTS packages with another, and load balancing ideas with a third. All of those people had no idea what I was talking about. All of them remarked the same thing to me: "Whoa, you know a lot about a lot".

And that was it. Just some simple recognition that I wasn't awful from some people I respected. That I had something to contribute after all. And my confidence spun around 180°.

Diva me.

I immediately started looking for other work and setting up my current company to survive without me. A few months later I landed a killer job at a brand new start up and doubled my salary.

I was now doing exciting meaningful work for people that respected me. And I was having a hell of a lot of fun. Ever since every step has been a strategic step forward. I've demanded a lot more of the companies I work for and my work life has been generally awesome.

The Takeaway

If you are riddled with doubt, please stop and list out your accomplishments. If you don't think you've "accomplished" anything at least just write down what you do.

I promise it's more than you think. And if you think that list should be longer or more meaningful, then here's your homework.

Write down a list of your future accomplishments. Then go do them.

Is it a custom component library? Go build one. Nobody has to even use it, just build it.

Is it orchestrating some lambda functions to replace Shopify? Do. It. Then write it down and tell people about it.

Or maybe you want to build your own headless CMS 🧐 Get it done. Then tell me about it!

I can't wait to see what you've done.

Photo by Matthew Henry on Unsplash

DIY HeadlessCMS + SSR with Vue & Netlify

Justin Boyson — Sun, 12 Jul 2020 20:58:41 +0000

Nuxt is awesome and you should probably use it, but sometimes it feels like overkill, and maybe you're an obstinate developer (like me!) who just wants to roll your own SSR so you can channel your inner Franky and do it your way. Well, welcome friend you're in the right place!

In this post we're going to use a basic Vue CLI app plus a few off the shelf plugins to get our Nuxt-lite functionality in place. Then we'll use the magic of webpack to bundle in our data and put together an "API" using nothing but fetch and a single netlify function. Let's do this 💪

First let's outline what we're building:

Nuxt-lite

SSR using @akryum/ssr Vue plugin
Auto page routing using auto-routing Vue plugin
Meta tags using vue-meta courtesy of the Nuxt team themselves (thanks!)

Git based Headless CMS

Set up our repo (we'll be using GitLab because I'm biased)
Setup netlify hosting + functions
Read data from a local json file using dynamic imports
Add a "user interface" with the super secret HTML attribute that they don't want you to know about
Save data directly to the repo using GitLab's REST API + fetch

The completed project's repo

I'm not going to go into very specific detail about each of these steps, so if you want to follow along you can clone the finished project here. I've tagged commits that represent the finished state of each step so you can try some things out, and then checkout the tag for a particular step if you need to start over.

I also recommend using your diffing tool of choice (GitKraken is nice) to compare the differences between tags and then trying out the changes yourself.

Let's get to work

Step 0: A basic Vue app

Heads up! This post assumes you are already comfortable building Vue apps. If not the docs are a great place to start. 💡

Create a Vue app and make it prettier

First things first lets bootstrap a barebones Vue app. If you don't have Vue CLI already install that bad boy:

And bootstrap an app:

vue create -b -n headless-cms-example

Note that I'm using the barebones install -b to skip all the example code and I'm skipping the git initialization -n so that it's easier to add the remote repo later.

Here are my answers to Vue CLI's pop quiz:

Manually select features
Babel, Router, Vuex, Linter/Formatter
Yes use history mode
ESLint + Prettier
Lint on save
In dedicated config files

Step 0.1: A prettier Prettier

Prettier is already opinionated, but apparently I'm even more so because I pretty much do this for every project I work on.

Create a .prettierrc file in the root of the project and paste in the following:

{
  "semi": false,
  "singleQuote": true,
  "trailingComma": "all"
}

Then run yarn lint --fix. SO MUCH BETTER.

Set up git and remote repo

Now would be a good time to get git set up and commit to a repo. I'll be using GitLab for this, but if you prefer [REDACTED] instead I assume you can follow along in [REDACTED] yourself. I'm also not going to spell these steps out completely as I am expecting my dear readers (that's you!) to have a decent working knowledge of git and online repos.

In a nutshell, create a new project and name it the same as your Vue app "headless-cms-example". Do not initialize with a README. Then follow the instructions to "Push an existing folder".

Excellent, now we can undo the terrible mistakes we will inevitably make later.

Step 1: Better looking dummy content + Tailwind

Anywho, now you have a fully functional and safely version controlled but terrible looking Vue app. Let's fix that real quick, because working on pretty things is more fun that working on ugly things.

First up, let's get tailwind installed and configured. This is a great article and is what I followed for this project.

The one thing the article doesn't mention is configuring tailwind to purge css that is not in use. Let's set that up now.

Open tailwind.js and add './src/**/*.vue' to the purge array. tailwind.js should look like this:

module.exports = {
  purge: ['./src/**/*.vue'],
  theme: {
    extend: {},
  },
  variants: {},
  plugins: [],
}

I won't go into detail about what all of that is doing because this isn't a tailwind tutorial, but I definitely encourage you to go play with tailwind if you haven't seen it before. It's an excellent tool for rapidly prototyping user interfaces.

And now we're going to cheat and grab some pre-made template content from tailbocks 😍 Sadly tailblocks does not deep link to their content so I've collected the blocks into a snippet on GitLab. You can grab them here if you're following along at home or just check out step-1 and skip ahead a bit.

Awesome! Now we have a nice looking static site.

Dynamic rendered content

Finally to complete our basic Vue app we're going to wire up the blog posts to some placeholder data.

For simplicity's sake we will only be editing the title of the blog posts, so our placeholder data will look like this:

  // Home.vue
  data() {
    return {
      posts: [
        {
          id: 1,
          title: 'Post 1',
        },
        {
          id: 2,
          title: 'Post 2',
        },
        {
          id: 3,
          title: 'Post 3',
        },
      ],
    }
  },

Now we can loop over the posts in our template.

<div v-for="post in posts" :key="post.id" class="p-4 md:w-1/3">
...
<h1 class="title-font text-lg font-medium text-white mb-3">
  {{ post.title }}
</h1>
...
</div>

It's pretty basic but this sets us up for success by focusing on something we know very well so that we can do some sanity checking. When we pull in json data later all we'll have to do is set posts to an empty array and then fill it with our json data.

Go ahead and run yarn serve to see your project running if it isn't already.

Step 2: Easy SSR with CLI plugins

Thanks to Vue core team member Akryum we have vue-cli-plugin-ssr.

To get SSR set up start by running vue add @akrum/ssr

Aaaaaand that's it. I'll be honest, when I first set out to do this I had intended to roll my own SSR as per the docs but after trying the plugin like we did above, it was just too easy.

Step 3: Also easy auto routing with more CLI plugins

I promise this is not just going to be a bunch of shell commands, bear with me. But yes we are doing another one vue add auto-routing

Aaaaaand it's broken.

So what's going on here? The problem is that the plugin is using ES6 modules that can't be run server side. To get around this we need to use the beforeApp hook that the SSR plugin gave us.

The core of what we need to do is move the offending modules and the createRouterLayout function into entry-client.js

import routes from 'vue-auto-routing'
import { createRouterLayout } from 'vue-router-layout'
...
const RouterLayout = createRouterLayout(layout => {
  return import('@/layouts/' + layout + '.vue')
})

When you install the auto routing plugin it overwrites your routes directly. Since we can't use the modules like that we use Vue Router's addRoutes method to add the dynamic routes once the app is bootstrapped and loaded on the client.

  async beforeApp({ router }) {
    router.addRoutes([
      {
        path: '/',
        component: RouterLayout,
        children: routes,
      },
    ])
    await loadAsyncComponents({ router })
  },

There we go. Now we have some sweet, sweet auto routing. If we add a .vue file in the pages directory the routes will be automatically created.

For example:

If you create pages/test.vue then you will get https://your-baller-site.com/test

Step 4: Meta info

SEO. All the cool kids are doing it. Ok, full disclosure, I am not a cool kid and I know nothing about SEO 😅, but I'm pretty certain you need to set meta "things".

To that end let's install vue-meta yarn add vue-meta

For the most part we're just following the get started guide from vue-meta's docs. The only bit that's specific to our setup is where explicitly to put the server side code.

For us that's entry-server.js and index.ssr.html

  return new Promise(async (resolve, reject) => {
    const { app, router } = await createApp()
    const meta = app.$meta()

    router.push(prepareUrlForRouting(context.url))
    context.meta = meta

    router.onReady(() => {
      context.rendered = () => {}
      resolve(app)
    }, reject)
  })

Here we've just added a reference to app.$meta on the context.

  <head>
    ...
    {{{ meta.inject().title.text() }}}
    ...
  </head>

And here we inject the meta items we want injected. I've only injected the title here because as I said before: I'm terrible at SEO.

With all of that we are now finished with our "nuxt-lite" application and are now ready to CMS all the things!

Step 5: Loading data from JSON files

This part is awesome in it's simplicity. Thanks to webpack and the fact that we are going to use git to update local files, we can simply import json right where we need it.

First move the inline posts array from index.vue to db/posts.json and format it accordingly. I like to use an online javascript to json converter for this. I won't link one here since I don't want to endorse any particular one, so I trust your Google instincts here.

In index.vue simply add a created hook like so:

  created() {
    import('@/db/posts.json').then(data => {
      this.posts = data.default
    })
  },

That's it! Now you have "live" data. Run the site yarn ssr:serve and check it out. Update the json file and see the titles change.

Noice.

Step 6: Saving data to the repo

Backend

We're going to be using Netlify's functions so if you don't already have it go install Netlify's CLI dev tool.

npm install netlify-cli -g

This isn't a "setting up Netlify functions" tutorial either so I'll skip the detail, but basically create a new Netlify site and hook it up to your repo.

Then login to netlify cli with netlify login if you are not already authenticated.

Once you're logged in you can cd in to your local project and run netlify init Choose the site you just created and we're ready for magic.

The easiest way to setup a netlify function is to use the cli. Create an empty functions folder and netlify.toml file at the root of your project.

At a minimum you need to set the functions directory, but here is my toml that will set you up for success.

[[redirects]]
  from = "/api*"
  to = "/.netlify/functions/:splat"
  status = 200

[build]
  functions = "functions"
  command = "yarn ssr:build"

[dev]
  framework = "#custom"
  command = "yarn ssr:serve"
  targetPort = 8000

That sets you up with a nice redirect so that you can call your function from /api/posts instead of /.netlify/functions/posts. It also configures the cli to work properly with our fancy ssr setup.

Now run netlify functions:create posts and select the node-fetch template. This will scaffold out a functions/posts directory. The only file we care about here is functions/posts/posts.js you can delete the rest. You will also need to install node-fetch so that it is available at build. yarn add node-fetch.

Ok! Now is a good time to make sure everything is wired up correctly. Run netlify dev and your site should be compiled and ready to serve. Go to the localhost url it gives you and make sure the site looks ok. Now let's test that new function by adding /api/posts to the end of your url. Something like http://localhost:8888/api/posts and it should show you a silly joke.

If all is well we can update this function to save data to our repo. First we need to pull in our private token and create a little string helper to format the url the way GitLab's API expects.

const GL_PRIVATE_TOKEN = process.env.GL_PRIVATE_TOKEN
const path = 'src/db/'.replace(/\//g, '%2F')

GL_PRIVATE_TOKEN is an environment variable that I added directly in the settings for the site on netlify.com. Netlify dev actually pulls these in locally and makes them available which is pretty cool.

Next is replacing the example GET call with a PUT.

const response = await fetch(`https://gitlab.com/api/v4/projects/${repoId}/repository/files/${path}posts.json`,
  {
    method: 'PUT',
    body: JSON.stringify({
      commit_message: 'Update posts',
      branch: 'master',
      author_name: 'CMS',
      content,
    }),
    headers: {
      'CONTENT-TYPE': 'application/json',
      'PRIVATE-TOKEN': GL_PRIVATE_TOKEN,
    },
  },
)

This is all pretty basic fetch usage. We swap in the URL for GitLab's files API, pass data through stringify in the format that GitLab expects, and set our private token in the header.

Finally we tweak the return to match our new format:

const data = await response.json()

return {
  statusCode: 200,
  body: JSON.stringify(data),
}

Sweet! Now that the backend is ready let's build up a quick and dirty interface so that we can live edit directly on the site.

Frontend

For our dead simple interface we're going to use a built feature of plain old HTML: contenteditable.

We simply set contenteditable="true" on our title and use a Vue method to submit.

<h1
  ...
  contenteditable="true"
  @keydown.enter.prevent="update(post, $event)"
>

And to wire up our update method:

update(post, event) {
  this.posts.find(p => p.id === post.id).title = event.target.innerText
  fetch('/api/posts', {
    method: 'PUT',
    body: JSON.stringify({
      content: JSON.stringify(this.posts),
    }),
  })
},

Not the prettiest code ever written, but it gets the job done. Notice the double stringify calls. The content of body needs to be a string, but the posts array also needs to be formatted into proper JSON for it to work.

And that's it! Try it out. Changing a title and pressing enter should commit a change directly to the repo. This will automatically trigger a new Netlify build and update the site, or you can git pull locally to see the changes.

Neat!

Conclusion

Obviously this isn't a production ready full blown CMS, but hopefully you see the potential, and how simple the core concepts are.

If all you needed were blog posts, you could leave the backend code exactly as it is and just keep adding contenteditable to the pieces you need. You could even use a markdown parser and have markdown capabilities in your body text.

I plan to revisit this concept and try to package it up to be more consumer friendly by building UI components so that it can wrap different content types. Think image component where you just pick the src, and a "long text" component that accepts markdown.

I'd love to see a collection of developer coding blocks that anyone could piecemeal together without being tied to a single project. Where you could just use the repo file saving piece, but roll your own interface, or use the inline editor components, but save to a database instead.

This idea was born out of frustration with the current CMS offerings, and how hard it is to update them to your needs. I feel like the pieces should be simple enough, and tight enough in their scope that you are comfortable enough to take and leave what you please. Since every site is a little bit different, your CMS probably should be too.

That's it for today! Make sure to follow me for more coding shenanigans!

Photo by James Pond on Unsplash