DEV Community: David Y Soards

Setup PostgreSQL w/ pgvector in a docker container

David Y Soards — Fri, 29 Nov 2024 17:43:31 +0000

This post is a follow-up to my previous post on how to setup a local MySQL instance in docker.

RAG (Retrieval Augmented Generation) is quickly becoming the "Hello World" of AI apps. If you are working or playing with Large Language Models, you will no doubt need to create a RAG pipeline at some point. An important component of RAG is a vector database, and a popular option is pgvector - an open-source vector similarity search for Postgres. Here's how to quickly setup a local instance in a Docker container.

Pull and run the image

Pull the latest image from the docker repository. Replace 17 with your Postgres server version of choice.

docker pull pgvector/pgvector:pg17

Run the image, set the root user password, and expose the default Postgres port.

docker run -d --name <container_name> -e POSTGRES_PASSWORD=postgres -p 5432:5432 pgvector/pgvector:pg17

Create a db inside the container

With the Postgres server running, create a database inside the container.

docker exec -it <container_name> createdb -U postgres <database_name>

Connect to the database

Now we can connect to the database from our application and initialize the pgvector extension. I'll be using JavaScript. Setting up the entire application is outside the scope of this post, but you will need to install a couple dependencies:

pnpm add pg pgvector

Set a DATABASE_URL in your environment. I use a .env file. It should follow this format:

DATABASE_URL=postgresql://<pg_user>:<pg_password>@localhost:5432/<database_name>

For local development use @localhost, but if you are using something like docker-compose.yml and have named the service, you should use the name of the service e.g. @db.

In your application code, create the connection:

const pool = new pg.Pool({
  connectionString: process.env.DATABASE_URL,
});

Then, initialize pgvector and create a new table:

async function createStore() {
  // Initialize pgvector extension and create table if not exists
  await pool.query('CREATE EXTENSION IF NOT EXISTS vector');

  return {
    vectorStore: await PGVectorStore.initialize(embeddings, {
      postgresConnectionOptions: {
        connectionString: process.env.DATABASE_URL,
      },
      tableName: 'documents', // Default table name
    }),
  };
}

With the vectorStore setup, you can add content to it using vectorStore.addDocuments and query for context using vectorStore.similaritySearch.

That's it for this post. Maybe next time I will explore more specific uses of pgvector, and/or using it with Drizzle ORM! 👋

Switch from NGINX to Caddy

David Y Soards — Wed, 11 Sep 2024 19:08:33 +0000

Simplify your reverse proxy setup

I switched the reverse proxy on my Ubuntu server from NGINX to Caddy and it really simplified things.
Below are the steps I took:

Install Caddy

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

Check that the install worked

sudo service caddy status

If NGINX is installed, you'll probably see an error that port 80 is already in use at first.

I replaced all the individual files in conf.d with a single Caddyfile. It's also possible to use the sites-available / sites-enabled pattern, but I don't see the benefit. I actually really like having all the config in one file. It's very easy to work with.

Before

# root.conf

server {
        listen 80 default_server;
        listen [::]:80 default_server;
        server_name _;
        location / {
                return 404;
        }
}

# website1.conf

server {
    listen 80;
    listen [::]:80;
    server_name website1.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_cache_bypass $http_upgrade;
    }

    location /api {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_cache_bypass $http_upgrade;
    }

    location /auth {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_cache_bypass $http_upgrade;
    }

}

# website2.conf

server {
    listen 80;
    listen [::]:80;
    server_name website2.com;

    location / {
        proxy_pass http://localhost:8081;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_cache_bypass $http_upgrade;
        auth_basic "Restricted Content";
        auth_basic_user_file /etc/nginx/.htpasswd;
    }

    location /api {
        proxy_pass http://localhost:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_cache_bypass $http_upgrade;
    }
}

After

sudo nano /etc/caddy/Caddyfile

# Caddyfile

rootdomain.com {
        respond 404
}

0.000.00.000:80 {
        redir https://rootdomain.com{uri}
}


# site 1

website1.com {
        reverse_proxy :8080
        reverse_proxy /api/* :3000
        reverse_proxy /auth/* :3000
}


# site 2

website2.com {
        reverse_proxy :8081
        reverse_proxy /api/* :3001
        basic_auth {
                username $hashed$.password4321
        }
}

Not bad, eh?

Restart Caddy

sudo systemctl reload caddy

Fix SSL Config

I'm using Cloudflare for DNS which turns on their proxy by default. After updating to Caddy with it's built in SSL (an amazing feature btw), I got an ERR_TOO_MANY_REDIRECTS error in the browser. The solution was to change Cloudflare's SSL Config to "Full (Strict)". The problem seems to be fairly common and I found the answer here on the Caddy Community site.

Navigate to Websites in the sidebar > choose the site.
Then choose SSL/TLS in the sidebar > click Configure.
Under Custom SSL/TLS > select Full (Strict).

Remove NGINX

sudo apt remove nginx
sudo apt-get remove --purge nginx*

# maybe
sudo rm -rf /etc/nginx
sudo rm -rf /etc/init.d/nginx
sudo rm -rf /var/log/nginx
sudo rm -rf /var/cache/nginx/
sudo rm -rf /usr/sbin/nginx

Thanks for reading! 👋

Quick Tip: Setup a local MySQL in a docker container

David Y Soards — Sun, 14 Jul 2024 21:02:38 +0000

I've been working through the tutorials in the Go docs (which are super helpful and I highly recommend them) and for the section on "Accessing a relational database", I needed an instance of MySQL.
Not wanting to install it on my local machine, I opted to use docker instead. Here's how I got a quick throwaway instance up and seeded it with minimal effort.

Pull and run the image

Pull the MySQL image from the docker repository. This step can be skipped if mysql has been pulled previously.

docker pull mysql

Run the image, set the root user password and expose the default MySQL port. latest is a tag that specifies which MySQL version to use.

docker run -d --name docker-mysql -e MYSQL_ROOT_PASSWORD=youshallnotpass -p 3306:3306 mysql:latest

Create a db and seed it

To run mysql commands on the db, open a bash inside the new container.

docker exec -it docker-mysql bash

mysql -u root -p
# Enter password: <MYSQL_ROOT_PASSWORD>

# mysql>

Create a database and name it.

mysql> create database new-db;

Switch to that new database.

mysql> use new-db;
# Database changed

Seed the database by pasting SQL commands directly into the bash window, such as this one for creating a todo table:

DROP TABLE IF EXISTS todo;
CREATE TABLE todo (
  id      INT AUTO_INCREMENT NOT NULL,
  text    VARCHAR(255) NOT NULL,
  done    BOOLEAN NOT NULL DEFAULT false,
  PRIMARY KEY (id)
);

INSERT INTO todo
  (text, done)
VALUES
  ('Do the Laundry', true),
  ('Clean the Kitchen', false),
  ('Mow the Lawn', false);

Verify it worked by running a select statement.

mysql> select * from todo;
+----+-------------------+------+
| id | text              | done |
+----+-------------------+------+
|  1 | Do the Laundry    |    1 |
|  2 | Clean the Kitchen |    0 |
|  3 | Mow the Lawn      |    0 |
+----+-------------------+------+
3 rows in set (0.00 sec)

You now have a local MySQL database with data you can query or write to running at 127.0.0.1:3306.
But you don't have to take my word for it! 🌈

Easy Forms for VueJS with Formspree

David Y Soards — Fri, 19 Apr 2024 13:49:32 +0000

Add a Contact Form to Your Vue or Nuxt App

Recently, I decided to consolidate some accounts by moving my domain registrations from Namecheap to Cloudflare and moving my static generated websites from Netlify to Cloudflare as well.

It was all pretty painless, but a few weeks later it dawned on me that I had been using Netlify Forms for the contact form on my portfolio site, and I hadn't bothered to change that code, so the form was broken.

Cloudflare doesn't have a 1:1 replacement for that feature but in their docs they have a few examples using Formspree, so I decided to give that service a try. Formspree has a generous free tier with up to 50 messages a month, which is more than enough for my needs.

Options API version

The Formspree docs have examples using HMTL, AJAX, and React (there's also an official React wrapper), but no example for VueJS. Below is what I am using in my Nuxt 2 app.

export default {
  name: 'Contact',
  data() {
    return {
      status: '',
    };
  },
  methods: {
    async handleSubmit(e) {
      try {
        const data = new FormData(e.target);
        const res = await fetch('https://formspree.io/f/<YOUR ENDPOINT>', {
          method: 'POST',
          body: data,
          headers: { Accept: 'application/json' },
        });
        if (res.ok) {
          this.status = "Thanks! I'll get back to you soon.";
          this.$refs.contactForm.reset();
          setTimeout(() => {
            this.status = '';
          }, 5000);
        } else {
          const json = await res.json();
          if (Object.hasOwn(json, 'errors')) {
            const errors = json.errors.map((error) => error.message).join(', ');
            throw new Error(errors);
          } else {
            throw new Error('Uh-oh! There was a problem submitting your form.');
          }
        }
      } catch (err) {
        console.error(err);
        this.status = err.message;
      }
    },
  },
};

<p v-if="status">{{ status }}</p>
<form v-else ref="contactForm" name="contactme" @submit.prevent="handleSubmit">
  <label>
    Name
    <input id="name" name="name" type="text" required />
  </label>
  <label>
    Email
    <input id="email" name="email" type="email" required />
  </label>
  <label>
    Message
    <textarea id="message" name="message" required></textarea>
  </label>
  <label class="hidden">Don't fill this out: <input name="_gotcha" /></label>
  <button type="submit">Send Message</button>
</form>

And so far, it's working great! Notice I also added a hidden "honeypot" input. Any form submitted with a filled in "_gotcha" input will be silently ignored by Formspree.

Composition API version

My portfolio site is static generated and I see no good reason to spend time updating it to Nuxt/Vue 3, but if I did I would definitely use Composition API and the code would look more like this:

// use script setup
const status = ref('');
const contactForm = ref(null);

async function handleSubmit(e) {
  try {
    const data = new FormData(e.target);
    const res = await fetch('https://formspree.io/f/<YOUR ENDPOINT>', {
      method: 'POST',
      body: data,
      headers: { Accept: 'application/json' },
    });
    if (res.ok) {
      status.value = "Thanks! I'll get back to you soon.";
      contactForm.value.reset();
      setTimeout(() => {
        status.value = '';
      }, 5000);
    } else {
      const json = await res.json();
      if (Object.hasOwn(json, 'errors')) {
        const errors = json.errors.map((error) => error.message).join(', ');
        throw new Error(errors);
      } else {
        throw new Error('Uh-oh! There was a problem submitting your form.');
      }
    }
  } catch (err) {
    console.error(err);
    status.value = err.message;
  }
},

Setup a VPS on Hetzner Cloud

David Y Soards — Tue, 09 Apr 2024 17:56:29 +0000

Lambda What, Lambda Who

For deploying my personal projects and websites I have mostly relied on the hobby tiers of serverless services like Netlify, Github pages, or Cloudflare pages. Prior to that I used simple FTP on shared hosting.

The DX of using serverless platforms is very appealing. Just connect a Github account, push your code, and they do all the work for you. For simple statically generated websites, it can't be beat. But when I started using lambda functions for server-side actions, I quickly hit some annoying edge cases because the runtimes are not 100% Node compatible.

That experience motivated me to setup my own VPS for deploying containerized applications. It was also an opportunity to learn how the abstractions and tools I use actually work. I chose Hetzner because it was the cheapest and I like German stuff.

These are the steps I took to get up and running with a VPS on Hetzner Cloud:

Hetzner Cloud

Start a Hetzner account at accounts.hetzner.com/signUp

Donate the blood of your first born child. I kid, but if you are from the U.S. you will need to verify your identity using your passport and then wait for a manual approval. My approval only took a couple hours.

Log into your new Hetzner account and choose Hetzner Cloud. In the Hetzner Cloud dashboard, start a new project and add a server. I used the following settings for a basic server to host my side projects.

Location

Choose the nearest location. For me it was (Ashburn, VA) us-east.

Image

Either choose Ubuntu OS or if you plan on using Docker, you can switch to Apps and select Docker CE. It will give you the latest Ubuntu OS with Docker Community Edition pre-installed. If you prefer, you can also install Docker yourself later.

Type

Shared cVPU
x86 (Intel/AMD)
CPX11 - 2GB Ram / 40GB SSD

Networking

Select both IPv4 and IPv6. IPv6 only is a tiny bit cheaper, but you will almost definitely still need IPv4 also.

SSH Keys

Add an SSH Key. Github has a nice guide on generating SSH keys. Lately I've been using 1Password's SSH agent and I like how I can easily use the same keys on different machines.

Skip for now

Volumes, Firewalls, Backups, Placement groups, Labels, and Cloud Config can be configured later if you need them.

Name

I used the default name.

Click Create & Buy Now.

Configure your server

Now it's time to SSH into the server and set it up.

Copy your new server's IP Address and open a terminal.

ssh root@<server_ip_address>

The first time you will be prompted to add the server's fingerprint to your known_hosts.

Updates

Run system updates to make sure we are using the latest, greatest, and most secure packages.

sudo apt-get update

sudo apt-get upgrade

SSH

Create a new sudo user.

sudo adduser <new_user_name>

usermod -aG sudo <new_user_name>

Add the public SSH key to your new user on the server.
To do that, switch to your new user.

su <new_user_name>

Then make a new .ssh directory.

mkdir ~/.ssh

To that directory, add a new file authorized_keys. Open that file with nano and paste in your public key.

nano ~/.ssh/authorized_keys

End your session and log back in with your new user to make sure SSH is working properly.

ssh <new_user_name>@<server_ip_address>

Now that you can ssh in with your username, you should dIsable login via the root user.
Navigate to the ssh directory and edit the sshd_config file. You may want to disable login via password entirely as well.

cd /etc/ssh
nano sshd_config

# sshd_config

PermitRootLogin no
PasswordAuthentication no

A lot of people recommend changing the default SSH port, but I left mine on 22.

For convenience you can edit your local .ssh/config file like so:

Host <nickname>
  HostName <server_ip_address>
  User <new_user_name>
  PreferredAuthentications publickey

With the above config, instead of typing ssh <new_user_name>@<server_ip_address> every time, you can just type ssh <nickname>.

UFW

Enable Uncomplicated Firewall and allow ports for SSH.

sudo ufw enable
sudo ufw allow OpenSSH
sudo ufw allow 22

Fail2Ban

Install Fail2Ban to prevent brute force attacks.

sudo apt install fail2ban

To configure, copy the jail.conf to jail.local and edit the file with nano.

cd /etc/fail2ban

# copy conf
sudo cp jail.conf jail.local

# edit
sudo nano jail.local

Make sure the sshd jail is enabled. It should be on by default.

[sshd]
enabled = true
port    = ssh

Nginx

Install Nginx and allow ports 80 and 443 on your firewall.

sudo apt-get install nginx
sudo ufw allow 'Nginx Full'

Setup reverse-proxy to allow hosting multiple containers on a single server. Each container will be accessed publicly through a subdomain.

There are several different methods for configuring reverse-proxy. Using sites-enabled / site-available has long been the convention for Debian/Ubuntu, but a lot of people recommend avoiding it. I find it overly complicated.

A simpler method is to add a *.conf file to the conf.d directory for each subdomain.

cd /etc/nginx

# conf.d/subdomain.conf

server {
        listen 80;
        listen [::]:80;
        server_name subdomain.example.com;
        location / {
                proxy_pass http://localhost:3000;
                proxy_set_header Host $host;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        }
}

To only use subdomains and remove the default Nginx page from your root domain, disable default in sites-enabled.

sudo unlink sites-enabled/default

And return a root 404 page instead.

# conf.d/root.conf

server {
        listen 80 default_server;
        listen [::]:80 default_server;
        server_name _;
        location / {
                return 404;
        }
}

Restart Nginx.

sudo systemctl restart nginx

Docker

If you didn't install Docker when you added your server, install it now by following instructions in the docs.

unattended-upgrade

Keep your system up to date automatically by installing unattend-upgrade.

By default it only auto updates security updates, but you can configure to update other packages as well. I left it on the default settings.

# install
sudo apt install unattended-upgrades
# configure
sudo dpkg-reconfigure unattended-upgrades
# check is running
sudo systemctl status unattended-upgrades

git

Install git so you can clone your repos, build them on your server, and share with the world.

apt-get install git

Congrats, you're officially a system admin! 🤜🤛

Next time, we will actually deploy a Node.js app in a Docker container.

Quick Tip: Breaking Vue's Reactivity

David Y Soards — Thu, 07 Mar 2024 14:33:51 +0000

VueJS is my front-end framework of choice. I use it at work and on various side projects. I love Vue's opt-in style reactivity engine (as opposed to React's opt-out style), but on occasion I find myself needing to purposely break the reactivity of a value.

One such situation that I have run into on multiple occasions recently is when using a confirmation dialog. It's a good practice when deleting an object through a UI, to not immediately perform the delete on the initial click, but to first confirm the destructive action with the user. That's because preventing errors is better than helping users recover from them. This principle is #5: Error Prevention on Jakob Nielson's 10 Usability Heuristics for User Interface Design

Let's say I have an object from a list selected and I click Delete. To confirm this action, I show a dialog that display's the selected object's name along with a question asking if the user is sure they want to delete it.

To accomplish this, I save the selected object to a ref called selectedObj and I use selectedObj.value.name in the text of the confirmation.

If the user clicks "Yes, Delete", we fire off a delete request, reset selectedObj to undefined, and close the dialog.

But because selectedObj is a reactive ref, as the dialog is fading out the name will disappear and the remaining text will shift suddenly, which is a pretty janky UX.

const selectedObj = ref();
const isConfirmOpen = ref(false);

async function deleteObject() {
  if (selectedObj.value?.id === undefined) return;
  await http.delete(`/api/item/${selectedObj.value.id}`);
  selectedObj.value = undefined;
  isConfirmOpen.value = false;
}

The simple solution is to make a non-reactive copy of the name before opening the dialog. Since the name value is a string, we can just copy it to a let and use that in the dialog's text.

let confirmObjName = '';

function handleDeleteObject() {
  // make a copy of the preset name before opening the confirm modal
  confirmObjName = selectedObj.value?.name ?? '';
  isConfirmOpen.value = true;
}

<!-- button with click handler -->

<button type="button" @click="handleDeleteObject">Delete Object</button>

<!-- modal component -->

<DModal v-model:open="isConfirmOpen" @confirm="deleteObject">
  <p>
    Are you sure you want to delete
    <span class="font-semibold">{{ confirmObjName }}</span>? This action cannot be undone.
  </p>
</DModal>

If we needed to break reactivity of the entire selectedObj we could copy it using Vue's toRaw method.

let selectedObjCopy = toRaw(selectedObj.value);

However, this is not necessary if all we are copying is a primitive value like a string.

Now when I set selectedObj to undefined after sending the delete request, the name of the object will no longer disappear before the dialog closes.

Simplify Dark Mode w/ Radix Colors & Tailwind

David Y Soards — Thu, 22 Feb 2024 14:29:42 +0000

I've been using Tailwind CSS both at work and on side projects for a few years now, and it has become one of my favorite tools. The defaults it provides, such as the color palette, and text sizes, are fantastic and more than adequate for most projects, but it's also completely customizable if needed. It's one of the first things I install on any new project I start. I don't even consider not using it at this point.

But there is one aspect of using Tailwind that I've always been somewhat on the fence about, and that is the dark variant. As per the docs, the dark variant "lets you style your site differently when dark mode is enabled".

A more standard approach to dark mode usually involves having a set of CSS custom properties (background color, text color, border color, etc.) and changing the values of those properties based on the currently selected theme. I've described that process in a previous post.

Tailwind's dark variant requires you to set light and dark classes for every individual element. For example setting the background and text colors of an element looks like:

<div class="bg-gray-50 text-gray-900 dark:bg-gray-900 dark:text-gray-50">...</div>

This approach provides maximum flexibility, but it's pretty verbose and you end up repeating the same light/dark combinations over and over.

Radix

Enter Radix Colors. Radix is best known as a wildly popular library of primitives for React, but they have also released a "comprehensive color system for designing beautiful, accessible websites and apps."

Radix Colors uses a 12 point scale where each step is designed for specific use cases. For example 1 is "App Background" and 12 is "High Contrast Text". The best part about this system though, is that each color scale has a light and dark version. By applying a "dark" class to the <html> or <body> element, dark mode will "just work!" And because the system was designed with accessibility in mind, you can guarantee that you won't have any contrast issues just by following the recommended applications.

Here's how to set it up with Tailwind:

First, install Radix Colors. I'll assume you already have Tailwind installed and setup for your environment.

pnpm add @radix-ui/colors

Import the light and dark versions of the colors you are using in your main CSS file. Doing this gives you the the CSS custom properties. Each color has an opaque version and also a transparent version. I'm using the opaque versions only below. Alpha versions should be imported separately.

/* tailwind.css */

@import '@radix-ui/colors/red.css';
@import '@radix-ui/colors/red-dark.css';
@import '@radix-ui/colors/mauve.css';
@import '@radix-ui/colors/mauve-dark.css';

Now, if you open your project in a browser and inspect the <html> element. You should see the properties listed in the Style tab.

Create your Tailwind classes

In your tailwind config file, write a function to create a tailwind color object with values 1-12. A simple for loop will do the trick.

// tailwind.config.js

function getColorScale(name) {
    let scale = {};
    for (let i = 1; i <= 12; i++) {
        scale[i] = `var(--${name}-${i})`;
        // next line only needed if using alpha values
        scale[`a${i}`] = `var(--${name}-a${i})`;
    }

    return scale;
}

Now we can use that function to set the colors in our theme.

// tailwind.config.mjs

export default {
    darkMode: 'class',
    theme: {
        extend: {
            colors: {
                accent: getColorScale('red'),
                gray: getColorScale('mauve'),
            },
        },
    },
};

Setting background and text colors on a div as I did above will now look like:

<div class="bg-gray-1 text-gray-12">...</div>

Using the Radix Color palette will take care of the majority of our dark mode concerns, but some overrides of the default behavior will likely be needed. And for those we can use the dark variant.

The Badge component used on my blog is a good example of using overrides. In dark mode the badge has a slight border and the background uses 2 with a 3 on hover, but in light mode there is no border and the background is a 3 with a 4 on hover.

<span
    class:list={[
        'font-sans inline-flex items-center rounded-sm bg-accent-3 px-2 py-1 font-base text-accent-10 ring-inset ring-accent-4 dark:ring-1 hover:bg-accent-4 dark:bg-accent-2 dark:hover:bg-accent-3',
        textSize,
    ]}
>
    <slot />
</span>

I really like this combination of Radix Colors doing most of the heavy lifting, and then handling "edge cases" with the dark variant.

Use More System Fonts

David Y Soards — Thu, 15 Feb 2024 14:42:01 +0000

Choosing which typefaces to work with, is one of the most impactful decisions a designer makes when starting a new project. For the web, this usually means looking thru Google Fonts, or Adobe Typekit, or some other online type foundry to find the perfect web font.

For years, I assumed I had to use a web font for all web projects because no serious person would even consider using system fonts. I think most designers have a similar attitude and are often too quick to reach for web fonts. Web fonts are great but there are also benefits to using System Fonts which are often overlooked.

Web or System

Web fonts are files (i.e. woff or woff2) that the browser has to download before it can properly render the page. The more font families and fonts weights needed, the more requests and more data the browser has to download. Loading web fonts can slow the initial page load or worse cause FOUT (Flash of Unstyled Text).

Perhaps your brand has established typographic guidelines, in which case you need to use specific typefaces which are likely only available as web fonts. In that case, you can improve load time and avoid FOUT by preloading the font file using rel="preload", like so:

<link rel="preload" href="/fonts/atkinson-regular.woff" as="font" type="font/woff" crossorigin />

If brand guidelines aren't a concern, I encourage you to at least consider using System Fonts. When I recently re-designed my blog, I made the conscious decision to forgo using any special web fonts and instead use good ol' system fonts. For body text I chose Charter and for headings I went with Helvetica Neue Condensed Bold and Helvetica Neue.

Charter is a great looking serif font designed by Matthew Carter, who later designed Georgia and Verdana also. At the time, it was designed for low resolution printing, and as a side effect it works nicely on screens.

Helvetica is an absolute classic. They even made a movie about it. It's used in logos for many of the biggest brands in the world. I figure it's good enough for my little blog.

Font Stacks

"But, David, those fonts are only available on MacOS!"

It's true, and consistency is one of the strongest arguments for using web fonts. The exact same font file will get loaded on every machine. But much like the layout of a responsive website is different at different screen sizes, your typefaces don't necessarily need to be exactly the same on every system either. They just need to be cohesive with one another and look good in context. By using a font stack in your CSS, you can ensure that different Operating Systems will use different but appropriate fonts.

Tailwind's default config has excellent font stacks for font-sans, font-serif, and font-mono. On all of my app side projects, I just use the font-sans system font stack. It ends up being SF Pro on Mac, Segoe UI on Windows, and Roboto on Linux. And I actually like the fact that the typeface in my web app ends up matching the typeface used in the Operating System.

/* font-sans */
font-family: ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';

With a web font, I typically limit myself to 2 or 3 weights at most, in order to reduce the amount of data that needs to be downloaded to the browser, but another advantage to using the system-ui font is that I have access to all of the available weights Thin to Black.

For my blog I modified the tailwind.config.js a bit to use Helvetica and Charter before falling back to the default font stacks.

// tailwind.config.js

export default {
  theme: {
    extend: {
      fontFamily: {
        cond: ['HelveticaNeue-CondensedBold', 'Helvetica Neue', ...defaultTheme.fontFamily.sans],
        sans: ['Helvetica Neue', ...defaultTheme.fontFamily.sans],
        serif: ['Charter', ...defaultTheme.fontFamily.serif],
      },
    },
  },
};

Comparison

If you are reading my blog on Windows (and you don't have Helvetica and/or Charter installed) you will see Georgia for body text and Segoe UI for headings, which is also a nice combination IMHO.

Below is the same screen on different systems.

Mac

Windows

Although I prefer the Mac version, both versions work well and are quite readable.

Conclusion

In conclusion, system fonts are underrated. Use more system fonts!

Resize Image on Save in Django Before Sending to Amazon S3 - No Lambda function required

David Y Soards — Sat, 26 Dec 2020 03:17:14 +0000

The Simple Way Using Pillow and a Memory Buffer

I've been leveling-up on my Django and Python skills lately, and I ran into a fairly common situation, that I could’t find a definitive solution for.

The Dilema

I have a users app with a simple Profile model, and I’m using django-storages to manage uploading my images and other static assets to Amazon S3.

If a users uploads a massive 4K image, that is never going to be displayed larger than 256px wide, I don’t want to have to store that. So I want to resize the image on save, before uploading it to AWS.

For storing images locally, I just have to install Pillow and override the save method in my Profile model like so:

from PIL import Image

def save(self, *args, **kwargs):
    super().save(*args, **kwargs)

    img = Image.open(self.image.path)
    if img.height > 512 or img.width > 512:
        output_size = (512, 512)
        img.thumbnail(output_size)
        img.save(self.image.path)

But it become a bit more complicated when using S3 buckets. I get a

NotImplementedError

Exception Value: This backend doesn't support absolute paths.

The Solution

Most of what I found online suggested removing the Pillow resize and writing an AWS Lambda function to handle the resize on upload. I initially tried that approach, but according to the AWS docs you shouldn’t use the same bucket for input and output, meaning I had to create a second S3 bucket just for resized images. I couldn’t figure out how to get that setup working with django-storages.

A second approach I found mentioned using a buffer to save the resized image into, and then saving that to AWS. The examples of this that I found were either incomplete or used old versions of python. Here is what actually worked for me using Python 3.8, Django 3.1.3 and Pillow 8.0.1:

user/models.py

from app.utils import image_resize

class Profile(models.Model):
    user = models.OneToOneField(User, on_delete=models.CASCADE)
    image = models.ImageField(default="profile-default.png", upload_to="profile_pics")

    def __str__(self):
        return f"{self.user.username} Profile"

    def save(self, *args, **kwargs):
        image_resize(self.image, 512, 512)
        super().save(*args, **kwargs)

app/utils.py

from django.core.files import File
from pathlib import Path
from PIL import Image
from io import BytesIO

image_types = {
    "jpg": "JPEG",
    "jpeg": "JPEG",
    "png": "PNG",
    "gif": "GIF",
    "tif": "TIFF",
    "tiff": "TIFF",
}


def image_resize(image, width, height):
    # Open the image using Pillow
    img = Image.open(image)
    # check if either the width or height is greater than the max
    if img.width > width or img.height > height:
        output_size = (width, height)
        # Create a new resized “thumbnail” version of the image with Pillow
        img.thumbnail(output_size)
        # Find the file name of the image
        img_filename = Path(image.file.name).name
        # Spilt the filename on “.” to get the file extension only
        img_suffix = Path(image.file.name).name.split(".")[-1]
        # Use the file extension to determine the file type from the image_types dictionary
        img_format = image_types[img_suffix]
        # Save the resized image into the buffer, noting the correct file type
        buffer = BytesIO()
        img.save(buffer, format=img_format)
        # Wrap the buffer in File object
        file_object = File(buffer)
        # Save the new resized file as usual, which will save to S3 using django-storages
        image.save(img_filename, file_object)

I’m overriding the save method still, and calling a function I’ve placed in utils.py of my main application. The following happens in the image_resize function:

The image_function checks if the image is too wide or tall and, if it is, saves a resized version first to a memory buffer and then to S3. Back in the save method we call super().save() to save the remaining fields. The super().save() needs to be called after the image.save() or both the original and the resized images will get uploaded to S3.

I hope that was helpful to someone. As always, thanks for reading and Merry Christmas and Happy Holidays!

Easy Headless Wordpress with Nuxt & Netlify part III

David Y Soards — Sun, 20 Sep 2020 19:40:40 +0000

Part 3 - Deploying on Netlify

Part 1 deals with setting up Wordpress as a Headless CMS.

Part 2 covers Vue, Nuxt and Tailwind.

Deploying your project to the web from a git repo is ridiculously easy using Netlify. I'm going to assume you are familiar with Github and have been committing your work from Parts 1 and 2 of this series.

Moving the local Wordpress install that we worked on in Part 1 to a live URL is outside the scope of this article, but I will say that I have had success using the pro version of WP Migrate DB. It is by no means the only option though.

Once your CMS is live you will need to change the axios baseURL in the Nuxt config.

nuxt.config.js



axios: {

  baseURL: 'http://yourlivesite.com',

},

Add site in Netlify

Obviously you are also going to need a Netlify account for this, so if you don't have one, you will need to create one. Sign up using your Github account and you will be able to access your repos.

In the Netlify dashboard, click New site from Git.

Under Continuous deployment click the Github button.

Pick the correct repo.

If it's not set already, set the Build Command to npm run generate, and the Publish directory to dist.

Click Deploy site.

Netlify will deploy your site to a randomly generated URL that will end in .netlify.app. You have the ability to make your own custom .netlify.app URL or use a "real" domain name.

Any time you push to this repo's master branch, Netlify will re-deploy the site for you. But the whole point of setting up a CMS was so non-developers could make changes and add content. So we also want to trigger a deploy anytime new posts are published or existing published posts are updated.

Generate Build Hook

Navigate to your new site in the Netlify dashboard and then to Site Settings -> Build & deploy -> Build hooks and click Add build hook. Give your build hook and name, and click Save.

Now we have access to a unique URL that we can use to trigger a build. If you click the dropdown arrow next to your build hook you, it will show you a cURL command that you can use to trigger a build directly from the terminal.

Trigger Build Hook in Wordpress

Back in Wordpress, we can hook into certain events and call the build hook. I initially tried to set this up myself following the instructions outlined in this article. It hooks into the publish_post, publish_page and post_update Wordpress hooks, and uses PHP's built in cURL library to trigger the build hook.

Sadly I could not get that code to work reliably. I'm not sure if it was permissions issues or very likely I was doing something wrong. Either way I opted to use a plugin, and I'm glad I did because it offers several benefits which greatly improved the user experience for the designers using the CMS.

The plugin is called Jamstack Deployments.

Once installed, navigate to Settings -> Deployments and enter the the URL of your build hook. The plugin gives you the ability to choose via checkboxes which Post Types, Taxonomies, and Post Statuses will trigger a build.

For purposes of this demo, you should check Events under Post Types and Published under Post Statuses.

It's nice to be able to turn the settings on and off via the dashboard. But my favorite feature of this plugin is the Status Bar that it adds to the Wordpress dashboard.

To get the Status Bar working properly, two URLs need to be added in the Jamstack Deployments settings. The URLs can be found in your Netlify dashboard under Site Settings -> General -> Deploy status badge. The first URL that ends in /deploy-status is the Badge Image URL and the second URL that ends in /deploys is the Badge Link.

With those settings entered, the current status of your Netlify site is displayed and updated in real-time in the Wordpress Dashboard.

The status bar also has a Deploy Website button. I found this feature extremely useful as well. If you know you or someone will be making a lot of updates to the site at once, you can temporarily turn off the auto-updates and just hit the Deploy button when you are finished.

And that's it! Our content-managed website built with Vue, and Wordpress is live and content is updating automatically.

As always, thanks for reading! If you have any quesions, please ask them in the comments

Easy Headless Wordpress with Nuxt & Netlify part II

David Y Soards — Tue, 15 Sep 2020 13:56:31 +0000

Part 2 - Nuxt & Tailwind

Part 1 deals with setting up Wordpress as a Headless CMS.

Part 3 covers deploying with Netlify and adding a build hook to our CMS.

Now that the JSON API endpoints are setup, the data from our Wordpress posts and media files can be queried, manipulated and rendered to static HTML files using Vue and Nuxt.

Create Nuxt App

Start a brand new nuxt project from the command line with

npx create-nuxt-app wp-nuxt

For purposes of this demo use the following settings:



? Project name: wp-nuxt
? Programming language: JavaScript
? Package manager: Npm
? UI framework: Tailwind CSS
? Nuxt.js modules: Axios
? Linting tools: ESLint, Prettier
? Testing framework: None
? Rendering mode: Universal (SSR / SSG)
? Deployment target: Static (Static/JAMStack hosting)
? Development tools: jsconfig.json (Recommended for VS Code if you're not using typescript)

With this configuration, and if you are using VS Code, I recommend placing the following in your workspaces's .vscode/settings.json to avoid conflicts between prettier, eslint, and Vetur and to correctly enable auto formatting of code on save.

settings.json



{
  "[html]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[css]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "eslint.validate": [
    "javascript",
    "vue"
  ],
  "vetur.validation.template": false,
  "css.validate": false,
}

Nuxt gives you access to Vuex (Vue's state management library) out-of-the-box. Navigate to the store/ directory and create a new file index.js. Most of our data fetching and manipulation will take place in this file.

store/index.js



export const state = () => ({
  events: [],
});

export const getters = {};

export const mutations = {};

export const actions = {};

Custom Fields

Before we can query the data we need to generate it in Wordpress. Add a few of the new custom post types we created in Part 1 and add some ACF fields to them. To do that, go to Custom Fields -> Field Groups -> Add New in the Wordpress dashboard. If you're new to ACF the documentation is actually pretty good.

For this demo, create a new Field Group named Events and set the Location to "Show this Field Group if - Post Type is equal to Event".

Add 4 Required fields with the following settings:



Label: Speaker
Name: speaker
Type: Text

Label: Start Time
Name: start_time
Type Date Time Picker

Label: End Time
Name: end_time
Type: Date Time Picker

Label: Image
Name: image
Type: Image
Return Format: Image Array

Add several Events and fill in the required fields as well as add some text to the default content area.

Navigate to http://headless.local/wp-json/wp/v2/events?page=1&per_page=100&_embed=1 and you should see your data being returned, including an acf object with keys that match the Name you entered in your custom fields.

Fetching Data

Back in your Nuxt repo in the Vuex store add a mutation for updating the events array, and an async action for fetching the events data.

store/index.js



export const mutations = {
  SET_EVENTS: (state, events) => {
    state.events = events;
  },
};

export const actions = {
  async getEvents({ state, commit }) {
    // if events is already set, stop
    if (state.events.length) return;
    try {
      let events = await this.$axios.$get(`/wp-json/wp/v2/events?page=1&per_page=100&_embed=1`);
      // filter out unnecessary data
      events = events.map(({ id, slug, title, content, acf }) => ({
        id,
        slug,
        title,
        content,
        acf,
      }));
      commit('SET_EVENTS', events);
    } catch (err) {
      console.error('getEvents', err);
    }
  },
};

The @nuxtjs/axios module that was installed when we ran create-nuxt-app gives us access to this.$axios.

Using $get gives immediate access to the data and doesn't require the usual .then(res => res.data) at the end of the call, which is a pretty cool feature IMO.

Before this will work as is though, we have to add our baseURL to the axios object in the nuxt config file.

nuxt.config.js



axios: {
  baseURL: 'http://headless.local',
},

Now we call the action in the created hook of a component.

index.vue



<script>
import { mapState, mapActions } from 'vuex';
export default {
  computed: {
    ...mapState(['events']),
  },

  created() {
    this.getEvents();
  },

  methods: {
    ...mapActions(['getEvents']),
  },
};
</script>

Alternatively, you could access the Vuex state and actions with this.$store.state.events and this.$store.dispatch('getEvents'), but I prefer to use the Vuex map helpers because it looks cleaner and shows in one place all of the global state and actions that are being used in a particular component.

Run Server Side

In order to make sure our fetch request runs on the server when we are generating our static HTML, we can add a Nuxt plugin. Create a file called data.server.js inside the plugins/ directory.

plugins/data.server.js



export default async ({ store }) => {
  await store.dispatch('getEvents');
};

And add the plugin to your nuxt config.

nuxt.config.js



plugins: ['~/plugins/data.server.js'],

Render to the page

Now we can use the data in the component's template.

index.vue



<template>
  <div class="max-w-screen-lg mx-auto p-10">
    <div v-for="(event, index) in events" :key="event.id">
      <div :key="index" class="lg:flex lg:max-w-screen-lg pb-8 lg:pb-16">
        <div class="lg:w-1/4">
          <img
            v-if="event.acf.image"
            :src="event.acf.image.sizes.large"
            :alt="event.acf.image.alt"
            class="w-64 h-64 object-cover mb-4 lg:mb-0"
          />
        </div>
        <div class="lg:w-3/4 lg:pl-8">
          <h4 class="text-xl lg:text-3xl font-normal leading-tight">
            {{ event.title.rendered }}
          </h4>
          <h3 class="lg:text-2xl font-bold mb-2">
            {{ event.acf.speaker }}
          </h3>
          <time class="text-sm lg:text-lg font-mono block mb-2">
            {{ event.acf.start_time }} - {{ event.acf.end_time }}
          </time>
          <p class="mb-4" v-html="event.content.rendered"></p>
          <nuxt-link :to="`/events/${event.slug}`" class="btn-sm lg:btn btn-green mb-2 mr-2">
            Event Info
          </nuxt-link>
        </div>
      </div>
    </div>
  </div>
</template>

Here I'm using utility classes from the Tailwind CSS framework that we also installed when we ran create-nuxt-app. If you'd like to learn more about Tailwind, the docs for it are some of the best I've ever used.

If you've followed along until this point you should have something that resembles this:

But what if we need to show the events in order by date. For that we can use a getter, which I think of as a computed property for Vuex state.

store/index.js



export const getters = {
  sortedEvents: (state) => {
    return state.events.slice().sort((a, b) => new Date(a.acf.start_time) - new Date(b.acf.start_time));
  },
};

Because the sort method mutates the original array, unlike map, filter, or reduce, I'm first using the slice method with no arguments to create a shallow copy and then sorting the copy.

Now add the following to your component:

index.vue



- import { mapState, mapActions } from 'vuex';
+ import { mapState, mapGetters, mapActions } from 'vuex';
export default {
  computed: {
    ...mapState(['events']),
+    ...mapGetters(['sortedEvents']),
  },
  created() {
    this.getEvents();
  },
  methods: {
    ...mapActions(['getEvents']),
  },
};

And in the template:



- <div v-for="(event, index) in events" :key="event.id">

+ <div v-for="(event, index) in sortedEvents" :key="event.id">

For a little more control over the format of our start and end times, install the date-fns nuxt module with npm i @nuxtjs/date-fns.

Then add @nuxtjs/date-fns to the build modules in your nuxt config, and import the methods you will be using. Being able to import only the functions you require is a huge performance advantage of date-fns over something like moment.js. This example only requires 1 method - format. For more info on date-fns check out the docs.

nuxt.config.js



buildModules: [
  '@nuxtjs/tailwindcss',
+  '@nuxtjs/date-fns',
],
dateFns: {
  methods: ['format'],
},

Now we can use $dateFns methods directly in our templates like so:

index.vue



- {{ event.acf.start_time }} - {{ event.acf.end_time }}
+ {{ $dateFns.format(new Date(event.acf.start_time), 'E h') }} - {{ $dateFns.format(new Date(event.acf.end_time), 'haaaaa') }}

Our Vue JS page rendered with content from the Wordpress JSON API is looking pretty good!

In Part 3 we will deploy our Nuxt app to Netlify and add a build hook so we can rebuild our site anytime new content is published.

Thanks for reading! Take a look at the source code for midwestdesignweek.com. 👀

relaydesignco / design-week-nuxt

If all of this setup is too much, or maybe you're just in a hurry, Netlify was a great repo made for just this purpose that you could use as a starting point. It was co-written by Vue Core Team member Sarah Drasner, and even has a companion article explaining its inner workings on Smashing Magazine.

This article and repo were extremely helpful for me when I was getting started.

netlify-labs / headless-wp-nuxt

🏔 Headless WordPress JAMstack Template

Easy Headless Wordpress with Nuxt & Netlify

David Y Soards — Sat, 12 Sep 2020 18:06:53 +0000

Part 1 - Setting up Wordpress

Part 2 covers Vue, Nuxt and a little Tailwind.

Part 3 deals with deploying with Netlify and adding a build hook to our CMS.

Recently, I was tasked with building the event website for AIGA's first annual Midwest Design Week.

Last year, I built the site for AIGA Louisville's Design Week using Gatsby and a handful of markdown files. The content was really only editable by myself or another developer, and that was fine at the time. (I wrote a couple articles about the experience here and here.

This year, however, members from 4 different city chapters were involved and needed to be able to easily add and edit content, so some kind of CMS was required.

The company I work for, Relay Design Co. also got involved as the Creative Sponsor. Because the stacks we use at Relay include both Vue JS and Wordpress, I opted to try using Wordpress as a headless CMS and build the front-end with Vue's Static Site Generator Nuxt.

Local Wordpress

The very first step is of course to spin up a Wordpress site locally so you can work on it. For this process I like to use local by flywheel. If you haven't tried it I highly recommend you do, because the entire process is literally 3 clicks and 3 text input fields.

For this demo I'm assigning the site domain to headless and it will available at headless.local. Depending on what you use it may be localhost:####.

Headless theme

Once your Wordpress site is up and running, navigate to /wp-content/themes/ and create a new folder named headlesstheme (or whatever you'd like).

Inside of that folder create the following files:

functions.php



<?php

if (!defined('ABSPATH')) {
    exit;
} // Exit if accessed directly

style.css



/*
Theme Name: Headless Theme
Theme URI: https://github.com/username/reponame
Author: Your Name
Author URI: https://yoursite.com/
Description: headless theme for using WP as a REST API only
Version: 0.1.0
Requires at least: 4.7
Requires PHP: 5.6
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Text Domain: headlesstheme
*/

index.php



<script type="text/javascript">
  window.location = 'https://yourfrontend.com';
</script>

If you would prefer that visiting the url of this Wordpress site not redirect to your front-end app, leave the index.php blank.

To make your theme look legit, add 1 more file to the new theme folder - an 800x600 PNG image file - and name it screenshot.png. This image is what will show up in the dashboard under Themes.

At this point you are ready to Activate your new theme.

3rd party plugins

Next, we need to install a few plugins to make using Wordpress as a CMS a little more convenient.

Classic Editor

Disables the new Gutenberg block editor.

Advanced Custom Fields

How this plugin is not part of core Wordpress at this point is beyond me, but as the name implies it adds the ability to add customized fields to posts, and pages. Without it, we would be limited to the default title, text content and feature image fields.

SVG Support

By default, the Wordpress Media Library doesn't allow SVG images because, since they are XML based, they could potentially pose a security risk. Just make sure anyone you give editing privileges to is someone trustworthy and it shouldn't be a problem.

If you prefer to avoid using a plugin, it is possible to enable SVG support just by add the following code to your functions.php file.



function allow_svg($mimes)
{
    $mimes['svg'] = 'image/svg+xml';
    $mimes['svgz'] = 'image/svg+xml';
    return $mimes;
}
add_filter('upload_mimes', 'allow_svg');

function fix_mime_type_svg($data = null, $file = null, $filename = null, $mimes = null)
{
    $ext = isset($data['ext']) ? $data['ext'] : '';
    if (strlen($ext) < 1) {
        $exploded=explode('.', $filename);
        $ext=strtolower(end($exploded));
    }
    if ($ext==='svg') {
        $data['type']='image/svg+xml' ;
        $data['ext']='svg' ;
    } elseif ($ext==='svgz') {
        $data['type']='image/svg+xml' ;
        $data['ext']='svgz' ;
    }
    return $data;
}
add_filter('wp_check_filetype_and_ext', 'fix_mime_type_svg', 75, 4);

I usually try to avoid using plugins and dependencies whenever possible, but in this case I found that by using this snippet the SVGs would upload and display nicely on the front-end, but would not display correctly in the Wordpress Dashboard, and getting them to do so consistently was more effort than it was worth. For this reason, I choose to use the SVG Support plugin.

JSON API

Out of the box, Wordpress gives you 2 default content types - posts and pages. And the Wordpress JSON API gives you endpoints to easily access both of these content types.
http://headless.local/wp-json/wp/v2/posts
and
http://headless.local/wp-json/wp/v2/pages

Adding ?page=1&per_page=100&_embed=1 will return all the available data.

Custom API plugin

Additional content types can be created and also queried using similar endpoints. The best place to put your code for creating these new post types is in a plugin.

To create a custom plugin, make a new folder inside /wp-content/plugins/ and name it headless-plugin (or whatever you'd like).

Inside that folder create a php file with the same name as your folder:

headless-plugin.php



<?php
/*
Plugin Name: Headless Plugin
Description: Custom setup for JSON API
Author: Your Name
Version: 0.1.0
Text Domain: headless-plugin
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
*/

if (!defined('ABSPATH')) {
    exit;
} // Exit if accessed directly

// ADD CODE FOR CUSTOM POST TYPES HERE

The following code will create a post type named Events:



// create events post type
add_action('init', 'create_post_type_events');
function create_post_type_events()
{
    $labels = array(
    'name'               => _x('Events', 'post type general name', 'headless-plugin'),
    'singular_name'      => _x('Event', 'post type singular name', 'headless-plugin'),
    'menu_name'          => _x('Events', 'admin menu', 'headless-plugin'),
    'name_admin_bar'     => _x('Event', 'add new on admin bar', 'headless-plugin'),
    'add_new'            => _x('Add New', 'Event', 'headless-plugin'),
    'add_new_item'       => __('Add New Event', 'headless-plugin'),
    'new_item'           => __('New Event', 'headless-plugin'),
    'edit_item'          => __('Edit Event', 'headless-plugin'),
    'view_item'          => __('View Event', 'headless-plugin'),
    'all_items'          => __('All Events', 'headless-plugin'),
    'search_items'       => __('Search Events', 'headless-plugin'),
    'parent_item_colon'  => __('Parent Events:', 'headless-plugin'),
    'not_found'          => __('No Events found.', 'headless-plugin'),
    'not_found_in_trash' => __('No Events found in Trash.', 'headless-plugin')
  );

    $args = array(
    'labels'             => $labels,
    'description'        => __('Description.', 'headless-plugin'),
    'public'             => true,
    'publicly_queryable' => true,
    'show_ui'            => true,
    'show_in_menu'       => true,
    'query_var'          => true,
    'rewrite'            => array('slug' => 'event'),
    'capability_type'    => 'post',
    'has_archive'        => true,
    'hierarchical'       => false,
    'menu_position'      => 5,
    'show_in_rest'       => true,
    'rest_base'          => 'events',
    'rest_controller_class' => 'WP_REST_Posts_Controller',
    'supports'           => array('title', 'editor', 'custom-fields'),
  );

    register_post_type('events', $args);
}

Make sure to use the same Text Domain that you specified in the comment at the top of this file.

Now we can query the Events using this endpoint http://headless.local/wp-json/wp/v2/events?page=1&per_page=100&_embed=1

It is also possible to create a custom endpoint for your new post types. The code below with create an events endpoint that can be accessed at http://headless.local/wp-json/mwdw/v1/events.



function events_endpoint($request_data)
{
    $args = array(
    'post_type' => 'events',
    'posts_per_page' => -1,
    'numberposts' => -1,
    'post_status' => 'publish',
  );
    $posts = get_posts($args);
    foreach ($posts as $key => $post) {
        $posts[$key]->acf = get_fields($post->ID);
    }
    return  $posts;
}
add_action('rest_api_init', function () {
    register_rest_route('mwdw/v1', '/events/', array(
    'methods' => 'GET',
    'callback' => 'events_endpoint'
  ));
});

Personally, I prefer to just work with the default endpoints.

ACF

Since we will be using Advanced Custom Fields to add content we need to add those fields to the data that is returned by the API. We can write a function to add the endpoints and then call that function on the rest_prepare_post_type hook for each post type using add_filter.



// add ACF object to default posts endpoint
add_filter('rest_prepare_post', 'acf_to_rest_api', 10, 3);
// adds ACF object to events endpoint
add_filter('rest_prepare_events', 'acf_to_rest_api', 10, 3);
function acf_to_rest_api($response, $post, $request)
{
    if (!function_exists('get_fields')) {
        return $response;
    }

    if (isset($post)) {
        $acf = get_fields($post->id);
        $response->data['acf'] = $acf;
    }
    return $response;
}

That's pretty much it for setting up Wordpress. In part 2 we will query our data from Vue/Nuxt and setup auto deploys using Netlify.

Check out the source code for my theme and plugin. 👀

relaydesignco / mdmw-rest-plugin

relaydesignco / wp-headless-theme

Thanks for reading!