Despite this, if you’re someone who relishes tinkering with real hardware, building an authentic system can be a truly satisfying and nostalgic experience.

That is why I wanted to put together my own retro PC. I chose Socket 462 and the Athlon XP platform—a great line of processors from the turn of the millennium which I loved back in the day.

My goal was to create a single machine that could handle DOS games from the 90s all the way up to Windows games from the early 2000’s, and for that purpose, Windows 98 SE seemed like the best fit.

Running Windows 98, you get real mode DOS (something removed in Windows ME), plenty of chipset and processor options, great driver support, and of course access to unofficial service packs to fix USB drives, networking, and performance issues.

I recently completed my build (pictured below!) and in this post I’ll go through the components I tested, problems I faced, and what I learned in the hope that it helps anyone else looking to build something similar.

Defining requirements

Before jumping onto eBay and grabbing random components, I’d suggest deciding on a socket type early on, otherwise you’ll be overwhelmed with choice. Decide what type of system you want to build and research what parts are readily available and within budget.

If you at least know what type of CPU you’ll use, you’ll have an easier time searching for components, and things like RAM should be mostly interchangeable should you need to test multiple motherboards with different chipsets.

For myself, I decided early on I wanted to build a Socket 462 machine—its more or less age appropriate (Athlon XP launched in 2001), powerful enough to run games from the early 2000’s, parts are easy to obtain, and it was the CPU I used in my youth. 

So my requirements were:

• Components from the early 2000s to run a wide variety of games in DOS and Windows 98
• Socket 462 Motherboard, preferably mATX to fit within a horizontal case
• Athlon XP processor
• AGP graphics port
• At least 2xPCI slots (ISA would have been nice for sound, but boards with ISA are rare for Socket 462, so I made this concession)
• Decent sound card with a Midi port and decent DOS support (lots more on this later)
• 512MB RAM (maximum recommended for Windows 98)
• Lots of beige

The case I picked certainly met the beige requirement; the CS101 from Evercase in the UK. They are retro styled modern cases that are inexpensive. It was actually cheaper to pick up a brand new case than get a crusty old one from eBay when I was looking!

I found a graphics card early on. While many folks recommend the GeForce 4 Ti line of cards for Windows 98 and DOS, these are now quite hard to come by for a fair price. I instead picked up a cheap GeForce 5700 FX from Facebook marketplace.

It’s an AGP 8x card with 256MB ram and decent performance. It also supports DirectX 9. The only downside is you’re unable to use older, preferred drivers. I used 56.64 in my build, from March 2004.

Finding the right chipset, sound card, and CPU combination

I’m writing this post having built my system, so I am now in a position where I’ve made several mis-steps selecting motherboards which you can learn from. I actually went through several different motherboards with VIA and SIS chipsets to find ”the one”, as well as a few different sound card options and CPUs. 

The Athlon XP-M Processors

First off let’s cover the CPU I opted for in the end; Athlon XP-M 2600+. 

The Athlon XP desktop processors are great; really good performance, but one thing they lack is the ability to change the multiplier via software—the XP-M allows this.

This is super useful when playing speed-sensitive games (such as Theme Park, Wing Commander, Civilization) because you can slow the system down to 486 speeds (using the setmul utility) without additional software running in the background.

One of the motherboards I obtained did not like this processor so consider this when searching. Once I had discovered the versatility of the XP-M, I made support for this a requirement.

Sound cards w/ DOS support

This is one of the most difficult things I found to get working. It’s no secret, ISA based sound cards are superior for DOS, but unless you find an exotic, obscure Socket 462 motherboard with an ISA port, its out of the question. So I stuck with PCI. I’ll cover the sound cards in more detail later on in the post, but for now we’ll just mention the underlying technologies used for these sound cards to support DOS.

Essentially for a PCI based sound card to talk to DOS applications it needs one of the following things available (in order of DOS compatibility):

• A SB-LINK/PC-PCI cable from the motherboard to the sound card so the two can communicate
• Distributed DMA (DDMA) support at chipset level
• A sound card with it’s own version of DDMA (such as ESS Solo cards which have their own TDMA method)
• Some kind of software/proprietary solution

SB-Link is not common on Socket 462 motherboards. I couldn’t find one so I think it’s safe to assume its as rare as an ISA port.

Jumping to TDMA (ESS Solo cards) some people have had good success with these, particularly on VIA chipsets), but I had issues with some games like Monkey Island crashing, so I didn’t go this route in the end even though I really liked the card itself (and its ESSFM chip which sounds really nice).

As for the software solutions, they vary based on the card you use. SoundBlaster Live! cards can use software, as do some others like Yamaha YMFs, and generally compatibility is good, however, they take up vital memory and often require EMM386 to be loaded to function, so compatibility with certain older DOS games can be limited.

DDMA is the way to go in my opinion. The challenge is finding a chipset that supports it. For SIS based chipsets, its fairly straightforward. Pretty much everything before and including the 963L chipset can support DDMA. For VIA, you have more limited options; VT82C586, VT82C596, and VT82C686A. Anything newer won’t support DDMA and you’ll be stuck using a software based TSR which uses up vital memory in DOS.

More details on chipsets can be found here.

Motherboard Testing

When searching for a suitable motherboard, I found that these were the most important things to check for:

1. BIOS features – Ideally, control over PCI IRQ assignments (which I found was more common in VIA chipsets). Searching for the model you can often find the original manual which shows what features were available.
2. Is it an OEM board? – Typically OEM boards from companies like HP have locked down BIOS and can also include proprietary connectors for USB and case controls. Google the model number—I found https://theretroweb.com/ to be a vital resource in determining board suitability.
3. Form factor – All my picks were mATX because of the case I wanted. If you have an ATX case you’ll have more options.
4. Capacitors – Look for bulging or leaky caps. One of my boards had some bad capacitors and quickly died. If you have power issues, its likely related to the capacitors.
5. Special requirements such as DDMA support for sound cards.

I tested the following motherboards to find one I was happy with.

I settled with the PC Chips M863G. While I do believe it was originally a budget board, It has DDMA support and reasonable performance, and so far its been reliable.

I did face a few issues with this board but I was able to overcome them:

• Upper Memory in DOS – Onboard devices such as ethernet used up upper memory blocks in DOS preventing the use of Expanded memory (unable to set page frame). The fix was to disable ethernet in the BIOS—you can toggle them back on as and when needed.
• IRQ Assignments – The BIOS settings were fairly limited. There was no way to reserve IRQ slots, and I had conflicts between the sound card and USB controllers. The fix was to disable the USB controllers before installing the sound card, manually set the IRQ in windows, and then re-enable USB. This sorted out the conflict.

The runner up was the MSI with VIA Chipset but unfortunately the lack of DDMA support was the deal breaker there. If you can get the ESS SOLO card working with it, it would be a decent pick because it did have some decent BIOS and better performance than the SiS boards.

Choosing a Sound Card

Unlike the GPU, finding a decent sound card can be tough. We’ve already gone over the technologies cards can use to maintain DOS support, but still, finding something decent that meets those requirements is difficult because there are so many options out there.

With our motherboard supporting DDMA, finding a card which takes advantage of this was paramount. Here is a list of the cards I tested across my motherboards and systems.

Your experiences may vary but I would choose either the ESS SOLO (if you’re on a chipset without DDMA support), or the Yamaha if you can get one. Both had decent DOS support but the Yamaha had the edge due to its DDMA support, and it worked better in Monkey Island Talky Edition which was important to me

In DOS, the Yamaha emulates a SoundBlaster Pro and gives access to the Midi port for external synthesisers. FM sound great, and in Windows you get XG midi which again, sounds fantastic. I wish that was also available in DOS but I guess you cannot have it all!

Putting it all together

Aside from the above, I finished the system off with 512MB RAM and a modern SFX PSU (which the case required). I had a spare HDD and DVD drive so I didn’t need to purchase those.

I also added and optional Gotek Flash Drive (instead of a floppy drive) because internal floppy drives can be unreliable. I actually picked up an external floppy drive to copy old disks I own to the Gotek for convenience.

Just including the parts I used and paid for, this is a breakdown of the costs for my build:

Considering some of the rarer parts I obtained, I think this ended up being fairly reasonable. The largest expense was that Sound Card—I don’t see many Yamaha cards crop up on eBay!

For the budget conscious, the CS101 has an optional PSU you can add for £20, desktop Athlon XP CPUs are cheap (I picked up a 2400+ for £10), and SoundBlaster Live! cards are readily available for £10, so you could easily get a comparable system for under £150 if you wanted.

Benchmarks

I ran 3D Mark 99 and 2000 benchmarks just to see how things ran. This is using Nvidia 56.64 drivers (older drivers won’t work with the FX 5700 card I have).

I don’t have any machines to compare to, but I’m happy with the performance under Windows. I have not installed too many games yet, but the newest game I’ve tried so far is Sim City 4 (from 2003) which runs flawlessly.

As for DOS gaming, well, I’ve hooked up my Roland MT-32 and I’ve been enjoying the classics; Transport Tycoon, Lemmings, The Secret of Monkey Island, Little Big Adventure, and so on. I’ve had very few compatibility issues with this setup so far so I’m pleased with the system overall.

If you’re curious about my software setup:

• The launcher in the video above is Launch Box for MSDOS
• I have three configs to choose from when entering DOS
  • Expanded Memory (emm386.exe and HimemX)
  • Extended Memory (just HimemX)
  • Conventional Memory
• I have several bat files to load drivers:
  • sound.bat which initialises the Yamaha sound card
  • mouse.bat which loads up Cute Mouse drivers
  • mpu.bat which loads up SoftMPU if a game requires it.
  • LoadCD.bat which loads CDROM drivers only when needed (to save on memory)

My expanded memory config leaves around 610kb conventional memory free which is enough for all the games I’ve tried thus far.

Resources

I wanted to finish off by listing a bunch of incredible resources I used to research parts, issues, solutions, and everything in between. They were vital to the success of this build.

• Vogons Forums – Covers hardware, software, DOS and everything. Great to search if you run into an issue, or want to know if anyone has used a particular piece of hardware before.
• Vogons Vintage Driver Library – Very useful because most of the things you get from eBay won’t have driver disks.
• Phils Computer Lab – Reviews of hardware, tutorials, software, and drivers. A great resource for retro computing information.
• The Retro Web – Lots of data on old motherboards.
• Archive.org – For software and drivers. Also check out the wayback machine if you need to get a driver from a site that no longer exists.

My 7th Year at Automattic

I’m approximately halfway through my 7th year at Automattic!

I’ve been working as an Individual Contributor (IC) with mostly JavaScript/TypeScript/React and PHP. I switched from working exclusively with PHP in 2019, and I’m having a great time working with Javascript, despite its quirks.

This year’s contributor graph from GitHub looks like this:

My contributions in the WooCommerce org were mainly within the WooCommerce Blocks repo. We’ve been building out both the new Cart and Checkout experience and the Store API that powers it—this will eventually land in WooCommerce core.

I’m still really excited about the Store API and the headless applications it enables (I chatted about this in an interview earlier in the year). It’s now reaching maturity and an acceptable level of stability, so I think it could land officially in core soon (hopefully 2022).

I had a little more confidence contributing to Gutenberg this year and received contributor status. That means I can merge things on GitHub. I worked on:

• Some improvements to default selections in the Combobox Component
• Again in Combobox, a fix to only force expanded state if the input has focus
• Fixing console errors when an Inner Block is deleted
• Fixing a memory leak in the useForceUpdate hook
• …and some other things which were not merged.

One cool thing we did this year was (as a team) to start the Epic React course. It covers the fundamentals and more advanced patterns, each with video explanation and coding exercises. Going into the course, I knew a fair amount about React Hooks, but it clearly explained how they worked in more depth and why. I realise it’s pretty expensive, but if it’s within your budget or your employer is willing to pay for it, it’s well worth doing, in my opinion.

Outside of work, I’ve dabbled with headless sites and GraphQL. I created a fun little app for generating random content for Dungeons and Dragons, which I stuck on Netlify.

The application has a WordPress backend that uses WP GraphQL—I wrote a series of posts covering this, including how to create a login system that may be worth reading if doing something similar.

I believe I’ve done a much better job balancing work and life this year, which is evident to me from my contributor graphs’ many voids (compared to previous years). Being able to switch off and do other things, especially on weekends, has helped with stress and burn-out, and I’m feeling much more relaxed in general—a positive change.

On my list for 2022; contribute to Gutenberg more, some leadership training should I want to go back to a lead role, and continue levelling up React and TypeScript skills.

Astrophotography

Looking back, I didn’t realise just how many incredible images I captured during 2021! I’ve got a decent dedicated astrophotography camera now (ASI 2600 MM), which is a mono camera that I’m using with narrowband filters. Compared to my previous cameras, it produces clean, low-noise images. It takes longer to process a colour image because of the number of frames needed per filter, but it is worth it.

My greatest banes are accurate focussing and the weather. A new “dome” is on my wishlist that will allow me to be better prepared for good weather conditions without having to drag 30kg of gear from the garage down the bottom of the garden!

You can see more of my Astro images on Flickr.

Unfortunately, I’ve had to take a short hiatus from imaging during these darker months because my telescope is buried in the garage while we remodel the house. Still, hopefully, by February, I can start imaging again. I’m hoping to revisit the Orion Nebula—my favourite target—in narrowband.

Other Photography

Getting out and about has been a challenge, given current events. I’ve not ventured far, which makes taking photos a little more tricky, especially when you’re a beginner and struggle with the subject matter. That said, we did do some travelling in the Summer months, and I took some lovely photos. A few of my favourites are below.

I’m currently rocking a Nikon z7ii. I love the ergonomics of the Nikon, and some of the new Z lenses are impressively sharp.

Movies, Games and Videos

Let’s be honest. 2021 wasn’t great for cinema (understandably). The streaming releases are convenient, but you lose some of the magic. Still, if I had to pick my favourites (note, I have not yet seen the new Spiderman Movie or Matrix Resurrections):

• Shang-Chi for me has probably been the best Marvel Movie this year. Likeable lead, nice origin story, good fights.
• The Suicide Squad for it’s dark humour. So much better than the first pitiful attempt. Some surprises too; James Gunn was not kidding when he said no-character was safe.
• Ghostbusters Afterlife was full of nostalga and did not dissapoint. Some of the characters did lack development and probably could have been cut without impacting anything, but overall it worked, Paul Rudd and Mckenna Grace were great, and it was so nice to see the original cast back in action.

There have been a few modern gaming titles this year I’ve enjoyed:

• Deathloop – I’ve not beaten this yet. It’s like groundhog day, with guns and lots of mystery.
• Cyberpunk 2077 – This received a lot of stick for being a buggy mess, but I didn’t experience many issues on PS5. Great story, fun gameplay. Kinda like Blade Runner meets Grand Theft Auto.
• Mass Effect Trology – Probably the best sci-fi RPGs of all time re-released on modern consoles. Number one shows it’s age a bit, but 2 and 3 are so good. Spent countless hours in this universe.
• Super Mario 3D World – I don’t think there is a bad mario game. Not as good as Odyssey, but me and my son enjoyed it.

I reckon I’ve played way more retro games this year. I started streaming my retro game playthroughs on Twitch. I play bad, die a lot, and don’t have many followers, but it’s good fun, and I’d be playing anyway. It’s definitely given me an excuse to break out the old consoles again and experiment with mods, upscaling, and modern RGB cables.

Everything else…

• For my retro streaming, this year I’ve procured a Sega Master System, an modded Super Famicom, Gamecube, a ZX Spectrum +2 (my old one died), and a BBC Micro. I’m amassing quite a collection!
• I bravely modded my Sega Mega Drive to play NTSC games at 60hz.
• I bravely tried to fix my Spectrum 48k and managed to replace the keyboard, but it ultimetely died. RIP.
• I’ve used Arduino before, but this year I got my first Raspberry Pi to play with. I built a Picade to emulate arcade games and I love it!

• My Dungeons and Dragons group (nerd alert) which started in Lockdown have been playing weekly throughout 2021 online using Roll20. This game is a lot of fun and we have some much needed laughs.

• I also had a go at being Dungeon Master for the first time which was a little scary, but it all worked out well; we did the Rick and Morty dungeon. I made lots of custom assets for the NPCs and a custom dungeon with Dungeondraft. It looked much better visually that the source material in my opinion.

• Our little family is growing. Dexter is now 3 years old. He’s definetely a handful, and working from home can sometimes be a challenge with all the distractions. But we manage. He also enjoys games and loves Mario (well, Luigi more, so he knows his stuff).

• Next year there will be a new challenge with Baby #2 arriving in March! I’m quite fond of the name Chuckie but that might be a hard sell to my wife. We shall see…

Thanks for reading my little round-up of 2021, and have a happy new year!

If you’re wanting to use a different OS such as RecalBox or Batocera, it can be a little challenging to get working because the included Picade X Hat (which controls sound and the joystick) only has a setup script for Retropie. Officially, other distros are not supported.

I had been using Recalbox on my other arcade machine, but I wanted to try Batocera this time; I love its simplicity, UI, and the default themes look great!

Here are the steps I had to take to get it working with the Picade. This assumes you have a Mac, Raspberry Pi 4, and a USB keyboard for setup.

Install Batocera Linux on an SD Card

Go ahead and download the Batocera image for your Pi. You need to flash this to an SD Card first (use Etcher). Once flashed you can pop it in your Pi and turn it on. Batocera will be installed.

Note that when booting for the first time, audio may be very loud, and volume controls won’t work. You can turn off music from the main menu, sound options which should suffice until we get the Picade setup correctly.

Bonus Step: Changing storage from ext4 to ExFat

Batocera, unlike RecalBox and Retropie, uses ext4 storage for Roms. If you’re managing your Roms over the network, or you have a Linux based PC, this is not a problem, you can leave it as-is. I however had quite a lot of data to transfer from my Mac, so to make this easier I formatted the storage as ExFat so I can copy things straight to the SD Card.

To do this, turn on the Pi and load Batocera. From the main menu go to System Settings > Developer > Format a disk and change ext4 to ExFat. Any data you’ve already copied will be deleted so do this step first if you intend to.

Configure Batocera for Picade Support

Now for the fun part. The Picade “Hat” (it’s a chip that sits atop the Pi) comes with an installer that gets it working with Retropie. This won’t work on Batocera (or other distros) though, so we need to set up the important parts manually.

Pop the SD Card into your Mac. A disk named BATOCERA will be mounted. We’ll be editing files here.

Step 1: Install the Picade overlay

The picade-hat installer compiles and creates a picade.dtbo file, but we don’t have access to the dtc tool it uses on Batocera, so we need to build it ourselves.

You can do this by checking out the Picade-Hat Git repository, installing dtc on your mac, and then running the dtc command in the picade-hat directory.

Alternatively, download the version I built below (it’s zipped):

With your `picade.dtbo` file in hand, copy it to your SD Card inside the /overlays/ directory.

Step 2: Edit the config.txt file

On your SD Card, find the config.txt file and open it up in your text editor. At the bottom of the file, add the following lines:

dtoverlay=picade
dtparam=audio=off

This tells Batocera to load the Picade overlay, which enables hardware support for the joystick and audio.

Also in this config, optionally, we can set up what keys the Picade joystick will map to. To better support RetroArch, I chose to map my joystick to the default RetroArch controls:

# key mapping
dtparam=button1=30 # A Key
dtparam=button2=31 # S Key
dtparam=button3=16 # Q Key
dtparam=button4=44 # Z Key
dtparam=button5=45 # X Key
dtparam=button6=17 # W Key
dtparam=enter=23 # I Key
dtparam=escape=1 # Escape
dtparam=coin=54 # Right Shift
dtparam=start=28 # Enter

When you’re done, save the file and eject the card. You can now put it back in your Pi and boot Batocera.

Step 3: SSH into Batocera

This isn’t as scary as it sounds. From another computer on your network you need to connect to Batocera using SSH. First ensure Batocera is connected to the same wifi network. On the main menu, go to Network and set up your wifi details.

Now from your other computer connect using:

ssh root@batocera.local

It may ask you to trust the certificate (answer yes), then will prompt for the SSH password which is linux.

We can now download the picade rules and sound config files and copy them to the correct places using the following commands:

mount -o remount,rw /boot
curl https://raw.githubusercontent.com/pimoroni/picade-hat/master/etc/udev/rules.d/10-picade.rules --output 10-picade.rules
curl https://raw.githubusercontent.com/pimoroni/picade-hat/master/etc/asound.conf --output asound.conf
mv 10-picade.rules /userdata/system/udev/rules.d/
mv asound.conf /etc/
batocera-save-overlay
reboot

This will configure and reboot Batocera and you should be good to go!

Edit: Batocera 31/32 seem to be working slightly differently. In 32 (dev version), the sound file is not required at all (yay!). And for the rules file, you may need to also copy this to /etc/udev/rules.d/ for things to work!

The only other tweak you may want to make is an edit in batocera.conf to make RetroArch easier to use. If you open that file up in an editor via SSH:

nano /userdata/system/batocera.conf

I’d suggest adding a shortcut key to open the menu when running RetroArch. I set it up so that pressing start and select (front two buttons on Picade) opens the main menu:

global.retroarch.input_menu_toggle_gamepad_combo = "4"

After saving changes, reboot the system.

Thanks to djibux who’s instructions on fixing RecalBox helped steer me in the right direction.

Lucky for us, WPGraphQL provides us with a user registration mutation we can use out of the box.

mutation registerUser {
  registerUser(input: {
    username:"new_user"
  }) {
    clientMutationId
    user {
      name
      slug
    }
  }
}

All we need to is build some client code to consume this. In this post I’ll be demonstrating this using ReactJS and the Apollo Client package (which I covered in a previous post) to make our requests to the server where WordPress and WPGraphQL are running.

Custom hooks

When we create a registration form it will need a way to send the form data to the server. For this we can create some custom React hooks.

useRegisterMutation

This hook provides us with a function named registerMutation that accepts a username, email, and password and then uses Apollo Client useMutation hook to make the GraphQL request. This function returns the result as a JavaScript promise.

/**
 * External dependencies
 */
import { gql, useMutation } from '@apollo/client';

const REGISTER = gql`
	mutation RegisterUser(
		$username: String!
		$email: String!
		$password: String!
	) {
		registerUser(
			input: { username: $username, email: $email, password: $password }
		) {
			clientMutationId
		}
	}
`;

export const useRegisterMutation = () => {
	const [ mutation, mutationResults ] = useMutation( REGISTER );

	const registerMutation = ( username, email, password ) => {
		return mutation( {
			variables: {
				username,
				email,
				password,
			},
		} );
	};

	return { registerMutation, results: mutationResults };
};

This hook can be used like this:

const { registerMutation, results } = useRegisterMutation();

useRegistration

I created another custom hook that consumes useRegisterMutation and does a little more handling for things such as error states and status that our registration form will later use.

One thing we do need to handle is error codes coming back from the WPGraphQL API—the codes are descriptive but need to be converted into a more human readable format if they are being displayed to the user:

const errorCodes = {
	invalid_username:
		'Invalid username or email address. Please check it and try again.',
	invalid_email: 'Invalid email address. Please check it and try again.',
	incorrect_password:
		'Incorrect password. Please try again, or reset your password.',
	empty_username: 'Please provide your username.',
	empty_password: 'Please provide your password.',
};

The hook itself uses the mutation hook we made earlier, tracks the status of requests (idle, resolving, resolved), and stores any error messages we get back from the server.

export const useRegistration = () => {
	const [error, setError] = useState(null);
	const [status, setStatus] = useState('idle');
	const { registerMutation } = useRegisterMutation();

	const register = (username, email, password) => {
		setError(null);
		setStatus('resolving');
		return registerMutation(username, email, password)
			.then(() => {
				setStatus('resolved');
			})
			.catch((errors) => {
				setError(errorCodes[errors.message] || errors.message);
				setStatus('resolved');
			});
	};

	return {
		register,
		error,
		status,
	};
};

Creating the user registration form

The registration form needs fields for username, email address, and password. It also needs to use the status and error state from the useRegistration hook we created earlier.

A basic version of the form in React would be as follows (I am using useState here to store field values).

import { useState } from 'react';
import { useRegistration } from 'hooks';

export const RegisterForm = () => {
	const [ username, setUsername ] = useState( '' );
	const [ email, setEmail ] = useState( '' );
	const [ password, setPassword ] = useState( '' );
	const { register, error, status } = useRegistration();

	const onRegister = ( e ) => {
		e.preventDefault();
		register( username, email, password );
	};

	return (
		<form
			onSubmit={ onRegister }
			className="register-form"
			autoComplete="on"
		>
			{ error && <div className="error-notice">{ error }</div> }
			<label htmlFor={ `field-username` }>Username</label>
			<input
				type="text"
				id="field-username"
				value={ username }
				autoComplete="username"
				onChange={ ( value ) => setUsername( value ) }
				disabled={ status === 'resolving' }
			/>
			<label htmlFor={ `field-email` }>Email</label>
			<input
				type="text"
				id="field-email"
				value={ email }
				autoComplete="email"
				onChange={ ( value ) => setEmail( value ) }
				disabled={ status === 'resolving' }
			/>
			<label htmlFor={ `field-password` }>Password</label>
			<input
				type="password"
				autoComplete="new-password"
				value={ password }
				onChange={ ( value ) => setPassword( value ) }
				disabled={ status === 'resolving' }
			/>
			<button
				className="button"
				onClick={ onRegister }
				disabled={ status === 'resolving' }
			>
				Create Account
			</button>
		</form>
	);
};

export default RegisterForm;

With this in place, our form looks like this:

Adding some basic form validation

To avoid making erroneous requests we can add some client side validation to our fields. We can add these validation rules in our form submit handler.

const [ passwordError, setPasswordError ] = useState( '' );

const onRegister = (e) => {
	e.preventDefault();
	setPasswordError( '' );
	if ( username.length === 0 ) {
		setPasswordError( 'Please enter a username.' );
		return;
	}
	if ( email.length === 0 ) {
		setPasswordError( 'Please enter your email address.' );
		return;
	}
	if ( password.length === 0 ) {
		setPasswordError( 'Please enter a password.' );
		return;
	}
	register(username, email, password);
};

With this change in place, registration will only be attempted if the username, email, and password fields are populated. This could be improved further by adding email format validation and so on.

Improving the password field

Our password field could be improved by giving some indication of password strength. For this I chose to use the React Password Strength Bar package. You can customise the scoreWords and shortScoreWord however you please to reflect password strength. For fun, I’m using a D&D theme

<PasswordStrengthBar
	password={ password }
	scoreWords={ [
		'critical fail',
		'okay',
		'good',
		'strong',
		'critical roll!',
	] }
	shortScoreWord={ 'critical fail' }
/>

In the above snippet we provide the current password, and it will access the strength and display it to the user:

You can see the final form on GitHub here.

Wrapping up

Our registration system is complete. The only other change I made (on the server side) was to disable new user emails:

remove_action( 'register_new_user', 'wp_send_new_user_notifications' );

You can see a working example of the registration form in my D&D app here, and the source code is also public on GitHub.

As I’ve said before, it’s very useful that WPGraphQL includes some of the account mutations out of the box. Whilst this is not unique to GraphQL (we could use the WP REST API if we wanted), I have found it very easy to work with from the client side.

Required GraphQL mutations

Unlike login and logout, WP GraphQL actually provides the mutations we require out of the box.

• Send Password Reset Email – This mutation requires a user name or email address and will trigger a password reset request to be sent to the user.
• Reset User Password – This mutation takes input of a username, the password reset key, and a new password. It sets the new password for the given user.

To see these mutations and others available to you, within WordPress admin you can head to GraphQL > GraphQL IDE.

Custom hooks

To interact with these mutations I created some custom React hooks. Note that I’m using Apollo Client to query the GraphQL API which I covered in my previous post.

useSendPasswordResetEmailMutation

This hook provides a sendPasswordResetEmail function. It takes a single parameter, username (which can also be an email address). It returns a promise allowing you to do something once the reset email has been sent.

import { gql, useMutation } from '@apollo/client';

const QUERY = gql`
	mutation SendPasswordResetEmail($username: String!) {
		sendPasswordResetEmail(input: { username: $username }) {
			clientMutationId
		}
	}
`;

export const useSendPasswordResetEmailMutation = () => {
	const [ mutation, mutationResults ] = useMutation( QUERY );

	const sendPasswordResetEmail = ( username ) => {
		return mutation( {
			variables: {
				username,
			},
		} );
	};

	return { sendPasswordResetEmail, results: mutationResults };
};

useResetUserPasswordMutation

We also need a custom hook to set a new password. This is used after the user has clicked the link in the password reset email.

My implementation of the custom hook returns a function that expects to be passed the login, a new password, and the “key” given to the user. Once validated, the user password will be updated, otherwise the promise will throw an error.

import { gql, useMutation } from '@apollo/client';

const QUERY = gql`
	mutation ResetUserPassword(
		$key: String!
		$login: String!
		$password: String!
	) {
		resetUserPassword(
			input: { key: $key, login: $login, password: $password }
		) {
			clientMutationId
		}
	}
`;

export const useResetUserPasswordMutation = () => {
	const [ mutation, mutationResults ] = useMutation( QUERY );

	const resetUserPassword = ( key, login, password ) => {
		return mutation( {
			variables: {
				key,
				login,
				password,
			},
		} );
	};

	return { resetUserPassword, results: mutationResults };
};

These hooks would be used as follows:

const { sendPasswordResetEmail } = useSendPasswordResetEmailMutation();
const { resetUserPassword } = useResetUserPasswordMutation();

// You would use these within an event handler or callback! It returns a promise.
sendPasswordResetEmail( 'test@email.com' );
resetUserPassword( key, 'test@email.com', 'newpassword' );

Whilst these mutations can be used directly, in my app I combined them into a single custom hook which handles status and errors. You can see this code on GitHub here (the useResetPassword hook).

Fixing the Password Reset Email

One gotcha I encountered was that the password reset email sent by WordPress links to the actual WordPress domain, rather than the headless site. We need to edit the email from WordPress to fix this—annoyingly the only way to do this is to replace the entire contents of the email, but you can customise this as much as you want which is a bonus.

add_filter( 'retrieve_password_message', function( $message, $key, $user_login, $user_data ) {
	$site_name = wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES );
	$message   = __( 'Someone has requested a password reset for the following account:' ) . "\r\n\r\n";
	/* translators: %s: Site name. */
	$message .= sprintf( __( 'Site Name: %s', 'morrics-magical-cauldron' ), $site_name ) . "\r\n\r\n";
	/* translators: %s: User login. */
	$message .= sprintf( __( 'Username: %s', 'morrics-magical-cauldron' ), $user_login ) . "\r\n\r\n";
	$message .= __( 'If this was a mistake, ignore this email and nothing will happen.' ) . "\r\n\r\n";
	$message .= __( 'To reset your password, visit the following address:' ) . "\r\n\r\n";
	$message .= HEADLESS_FRONTEND_URL . '/account/reset/' . rawurlencode( $user_login ) . "/$key\r\n\r\n";
	$requester_ip = $_SERVER['REMOTE_ADDR'];
	if ( $requester_ip ) {
		$message .= sprintf(
		/* translators: %s: IP address of password reset requester. */
			__( 'This password reset request originated from the IP address %s.' ),
			$requester_ip
		) . "\r\n";
	}
	return $message;
}, 10, 4 );

With the highlighted change in place, the password reset email will link to whatever URL you provide. In my example I am linking through to morrics-magical-cauldron.netlify.app/account/reset/<login>/<key>.

On the app side, I am mapping this URL to my reset password form component using Reach Router, but you could also use React Router or any other routing library. You just need to ensure your app can read the user login and key from the current URL, or query-string.

Forms

Now we have GraphQL setup on the server, some hooks to handle queries to the GraphQL API from the app, and we’ve fixed the password reset URL, we can build some form components to collect user data and trigger the events!

The following two form examples are just basic examples and are not complete, but should give you an idea of how the custom hooks work. You’ll still need to build in error handling and status messages for the final version!

Send Password Reset Email Form

export const ResetForm = () => {
	const [ username, setUsername ] = React.useState( '' );
	const { sendPasswordResetEmail } = sendPasswordResetEmail();

	const onReset = ( e ) => {
		e.preventDefault();
		sendResetPasswordEmail( username );
	};

	return (
		<form onSubmit={ onReset }>
			<label>Username or Email Address</label>
			<input type="text" value={ username } onChange={ ( value ) => setUsername( value ) } />
			<button onClick={ onReset }>Reset</button>
		</form>
	);
};

Reset Password Form

// resetLogin and resetKey come from the querystring/page URL and are passed to this component as props.
export const ResetPasswordForm = ( { resetLogin, resetKey } ) => {
	const [ password, setPassword ] = useState( '' );
	const { resetUserPassword } = useResetUserPasswordMutation();

	const onReset = ( e ) => {
		e.preventDefault();
		resetUserPassword( resetLogin, resetKey, password );
	};

	return (
		<form onSubmit={ onReset }>
			<label>Enter new password</label>
			<input type="password" value={ password } onChange={ ( value ) => setPassword( value ) } />
			<button onClick={ onReset }>Set New Password</button>
		</form>
	);
};

You can view my Reset Password Form component here, and my lost password form here. My final versions handle errors from the API, and show the user the status of their request.

Wrapping up

You can see a working example of the password reset flow in my D&D app here, and the source code is also public on GitHub.

It’s great that WP GraphQL handles password reset functionality by default. As I said in my last post, Apollo Client really makes the process of interacting with GraphQL simple, and (although I didn’t show examples) Reach Router is a fantastic routing library for sending users to the correct page of your app and accessing the query string. I highly recommend both!

In this post we’ll create a log-out mutation in GraphQL, and a custom React Hook to utilise it. I’ll be using Apollo Client to make the actual API calls.

Creating the GraphQL Mutation

We need to register a logout mutation in WP GraphQL first which logs the user out and unsets their authentication cookies.

Reminder: In GraphQL, a mutation query is something that modifies data and returns a value. It’s the equivalent of a POST request in REST.

This mutation doesn’t need any input; it just needs to unset the cookie (which in this case is a HTTP Cookie that React and JavaScript cannot see, nor access).

add_action( 'graphql_register_types', function() {
    register_graphql_mutation(
        'logout',
        array(
            'inputFields'         => array(),
            'outputFields'        => array(
                'status' => array(
                    'type'        => 'String',
                    'description' => 'Logout result',
                    'resolve'     => function( $payload ) {
                        return $payload['status'];
                    },
                ),
            ),
            'mutateAndGetPayload' => function() {
                wp_logout(); // This destroys the WP Login cookie.
                return array( 'status' => 'SUCCESS' );
            },
        )
    )
} );

This code would live in a custom plugin or your theme, on the server running WordPress.

Setting up Apollo Client

If you’ve not familiar with Apollo Client, it essentially provides us some React hooks with which we can make GraphQL requests to the server. For example, it provides a handy useMutation hook that runs a mutation query and returns the result. The getting started guide is here.

When using Apollo, you’ll likely want to wrap your App code in the Apollo Client context. For sake of completeness, here is a small example from my own app that sets up Apollo and ensures credentials are included with our requests (our cookies).

import { ApolloClient, InMemoryCache, ApolloProvider } from '@apollo/client';
import { BatchHttpLink } from '@apollo/client/link/batch-http';

const cache = new InMemoryCache( {} );
const httpLink = new BatchHttpLink( {
	uri: 'https://morricsmagicalcauldron.wpcomstaging.com/index.php?graphql', // My GraphQL Server
	credentials: 'include', // This sends our logged in cookie with the requests!
} );

export const useAppApolloClient = () => {
	return new ApolloClient( {
		link: httpLink,
		cache,
	} );
};

function App() {
	const client = useAppApolloClient();
	return (
		<AuthContextProvider>
			<ApolloProvider client={ client }>
				{ // Your App Code Here }
			</ApolloProvider>
		</AuthContextProvider>
	);
}

With Apollo client setup in this way, it can now be used from our other custom hooks.

Create a custom hook in React JS

With Apollo Client setup, we can create a custom hook in React JS to make our logout functionality reusable across the app.

import { gql, useMutation, useApolloClient } from '@apollo/client';

const LOGOUT = gql`
	mutation Logout {
		logout(input: {}) {
			status
		}
	}
`;

export const useLogoutMutation = () => {
	const apolloClient = useApolloClient();
	const [ mutation, mutationResults ] = useMutation( LOGOUT );

	const logoutMutation = async () => {
		// Remove all data from the store since we are now logged out.
		await apolloClient.clearStore();
		return mutation();
	};

	return { logoutMutation, results: mutationResults };
};

With this in place, we can create a logout button like this:

const { logoutMutation } = useLogoutMutation();

return ( <button onClick={ () => logoutMutation() }>
	Logout
</button> );

You can see where I implemented this in my app here and here. You can see in my app I created another hooked named `useAuth` to house my login, logout, and status queries which are used across the app.

Wrapping up

We now have the ability to logout from the app using a button! WP GraphQL will log the user out and destroy any cookies. You can see a working example this in my D&D app here, and the source code is also public on GitHub.

Apollo Client really makes the process of interacting with GraphQL simple, and takes care of all kinds of things like batching and cache for us. I highly recommend it if you’re using React!

via Instagram https://instagr.am/p/CMGQxclpm1N/

I could have tried using a serverless database such as FaunaDB, but I chose WordPress because of familiarity, what it gives you for free, and it’s flexibility when combined with WP GraphQL. I did however need to build a login system. To do this I created a GraphQL login endpoint, and handled user sessions using Cookies.

Cookies vs JWT

JWT (JSON Web Tokens) can be used to authenticate requests between parties. There is a decent overview of how JWT works here.

A plugin is available for WP GraphQL which handles authentication using JWT and adds a login endpoint. This looked promising, however, the most difficult thing about using JWT in the context of a web based React app is storage of the token. Whilst some articles recommend using localStorage, doing so is not secure—the token could be leaked using XSS.

Don’t store it in local storage (or session storage). If any of the third-party scripts you include in your page gets compromised, it can access all your users’ tokens.

JWT Authentication: When and how to use it

To keep our tokens secure our only option would be to store them in memory. The session would not persist if the browser tab was closed, making it less than ideal.

A better option, and the solution I went with, is using good old fashioned cookies (specifically HTTP Cookies which are inaccessible by JavaScript). I created a new GraphQL route that would set a HTTP cookie after successful login.

Side note: I did find a plugin for WP GraphQL which supports WP cookies, but I encountered browser compatibility (CORS) issues, so ended up rolling my own based on that.

Register a GraphQL Login Mutation

In order to login, we need to register a new endpoint with WP GraphQL. We do this by hooking in to graphql_register_types and adding our new mutation using the register_graphql_mutation function documented here.

We’ll call our mutation loginWithCookies and we’ll use inputFields to define which fields are accepted (username and password), outputFields to define the response, and mutateAndGetPayload to perform the login action:

add_action( 'graphql_register_types', function() {
	register_graphql_mutation(
		'loginWithCookies',
		array(
			'inputFields' => array(
				'login'      => array(
					'type'        => array( 'non_null' => 'String' ),
					'description' => __( 'Input your username/email.' ),
				),
				'password'   => array(
					'type'        => array( 'non_null' => 'String' ),
					'description' => __( 'Input your password.' ),
				),
			),
			'outputFields'        => array(
				'status' => array(
					'type'        => 'String',
					'description' => 'Login operation status',
					'resolve'     => function( $payload ) {
						return $payload['status'];
					},
				),
			),
			'mutateAndGetPayload' => function( $input ) {
				$user = wp_signon( 
					array(
						'user_login'    => wp_unslash( $input['login'] ),
						'user_password' => $input['password'],
					), 
					true 
				);

				if ( is_wp_error( $user ) ) {
					throw new \GraphQL\Error\UserError\UserError( ! empty( $user->get_error_code() ) ? $user->get_error_code() : 'invalid login' );
				}

				return array( 'status' => 'SUCCESS' );
			},
		)
	);
} );

We can use this mutation using a GraphQL query. You can view my usage of the login mutation in the React app here.

Setting the logged-in cookie

When you log in, WordPress sets cookies to track your session. These cookies have a httponly parameter so it is not readable through JavaScript.

I found the easiest way to give the headless site access to cookies was to set an additional cookie. After reviewing this, it doesn’t appear to be needed—previously I had issues with Safari but this no longer seems to be a problem. The regular WordPress login cookie is enough.

It doesn’t work yet though, if we try to login we’ll see a CORS error in the browser:

We need to send some additional headers so the browser does not reject the cookie!

Setting CORS Headers

The final piece of the puzzle is telling the browser it should accept the custom cookie when logging in from the headless site. We can define headers for our GraphQL routes using the graphql_response_headers_to_send hook.

add_filter( 'graphql_response_headers_to_send', function( $headers ) {
	$http_origin     = get_http_origin();
	$allowed_origins = [
		HEADLESS_FRONTEND_URL,
	];

	// If the request is coming from an allowed origin (HEADLESS_FRONTEND_URL), tell the browser it can accept the response.
	if ( in_array( $http_origin, $allowed_origins, true ) ) {
		$headers['Access-Control-Allow-Origin'] = $http_origin;
	}

	// Tells browsers to expose the response to frontend JavaScript code when the request credentials mode is "include".
	$headers['Access-Control-Allow-Credentials'] = 'true';
	
	return $headers;
}, 20 );

A detailed explanation of CORS can be found in MDN, as well as docs for allow credentials and allow origin.

Wrapping up

We’ve now created a GraphQL mutation which accepts login credentials and logs users in using a custom cookie, and we’ve set CORS headers so the browser allows the cookies to be used. Great! We can now hook this up to a login form in the React app.