payloadcms

typescript

illustrator

photoshop

mongodb

docker

vercel

northflank

playwright

nextjs

Any good software stack should be thoroughly tested. We use Jest for our unit tests and Playwright for our E2E / acceptance tests, however, Jest was around long before we started adding Playwright and we use the `data-testid` extensively in our project. Ideally, we have configured Playwright to use the same same ID instead of its own `data-playwright-id` but we have a backend team that had already implemented Playwright on some of their other projects and  wanted to keep things consistent.


They also wanted us to follow a pattern, where we can chain IDs to make things easier to find in the DOM. 

Take the following structure for example:


Beforehand, we would include `data-plaaywright-id` attributes on the individual components like so:

Unfortunately, this is cumbersome and restrictive to implement, and lacks the ability to chain IDs together to make unique, descriptive paths. 

This is where React Hooks come to the rescue! 

In this hook we want to do two things: pass in an initial ID as either a string (eg 'container') or as the object `{ 'data-playwright-id':  'some-id' }`. You may observe that the latter is what the hook setter (`setPlaywrightId`) returns. This is what makes it both reusable and chainable.

I styled the returned values of the hook after React's own `useState` hook as we'll see, but obviously you can do what you want. To the hook, you first need to declare it:

Since we'll be wanting to pass the root ID down, we can extend each component's prop to accept our hooks value. This is useful if you have to add IDs to many, many components and want a single source of  truth for the ID format.

So we have our components, we've created our root ID using our hook and we've extended the interfaces or components that will be using it, but now we want to extend it.

To do this, we can pass the `playwrightId` prop into a new instance of the hook in a child component.

Nesting a bit further down can get tricky. Fortunately, we can use some lightweight native functionality to pass props to children

Awesome! Now each child of Section will have the `playwrightId` prop with the chained IDs from its parents. Now to need to set it in the child Feature components

As a bonus, let's say we need both `data-playwright-id` for Playwright AND `data-testid` for Jest, BUT we don't want them created automatically in case they override other IDS. Easy. We can set an optional boolean argument in our hook and conditionally add on a property to our data attribute object

Rendering code languages in stylish blocks, especially when served from a CMS like Payload, can be tricky. Using JAMstack, developers can use the triple backtick method to denote which language they want to use, and most Markdown compilers are smart enough to know the  difference. 

For example, the following is written in Markdown:

But, like I said, rendering from a CMS can be awkward, as I found out writing this goddamn post.

So in this post, we're going to focus on two parts: the front-end, written in NextJS, and the backend, written with Payload.

Disclaimer: this post will not show you the  NextJS or Payload configurations as it's  out of scope

Payload can use something called Blocks when building content. The idea is that we break up our content - like code and text - into blocks, instead of using one to do the other (like using Rich Text to format with a code block, which may or may not work, and will always look shit.

Blocks belong in a sibling of /collections and ours will look a bit like this

The languages array is important - first it is the label and value which we'll use see in Payload, second its what the client needs to see (but we'll get to that later).

Next up is our Text Block, which will esentially be a Rich Text type in its own block

You can change this as you like, but its useful to be able to add media into it.

Once the blocks are created, you can add them to the resource's (in my case, Posts) fields array:

Once configured, we should be able to create an instance of content by selecting either CodeBlock or ContentBlock:

Blocks in Payload

content block

code block

Drop in some code, select a language and away you go!

CSS example

We all know that NextJS is extraordinarily powerful as is, but it really comes alive when mixed with other plugins.

In its most simple form, we take the language property we set on CodeBlock and use it to determine the  language for our rendered code.

Make sure your GraphQL query has the correct fields

Once queried successfully, you should be using a serialiser to render your content, and its fairly straightforward to add the language to Prism

Once everything is set up successfully, you should be able to render any language of your choosing that Prism supports (Tip: you can actually add languages eg HTML to the Payload list, but be careful).

You should hopefully be able to render multiple code blocks of varying languages in a funky blog post!

Payload is great but sometimes it can be difficult to visualize your app in all its multi-user glory when you have to keep populating everything by hand. Fortunately, we can leverage Payload's awesome constructor and models, along with the new-and-improved 

 to create rich linked documents that will help you to hit the ground running!

For this demo, we're going to create Users, Posts & Pages with Media, and some Tags and Categories for our sprinkles. You can obviously use what models you want, you maverick.

So let's start with the configuration. The gist here is that we initialize an instance of Payload using a separate seed script. This script will use the same Collections, database and config as our actual app but will have a start and finish. For this reason, we will declare our 

 directory, so we will need a slightly different 

So we have our tsconfig, our script (note how similar it is to the normal dev script), now we need the entry point file:

 it wouldn't do much other than initialize the payload config and then shut down. To do actual seeding, I'm going to use a class as I love their abilities to store and share state in a simple object. 

For educational purposes I've stripped out the logic for now and just left the method names so you can get a high-level view of the logic we'll be writing. But in case you can't be arsed to read the code, the script will seed the information in the following order:

Media (because we want our other collections to have media objects)

Posts (requires Media, Users, Categories and Tags)

You'll also notice that after the class we do two things:

We wrap the class in a function that initializes, drops previous data, seeds and then shuts down

We call that function in a promise chain. This part isn't strictly necessary but it helps with debugging and keeping it clean

Hopefully it's not too much and you can see where we're going. 

Let's start with our media. Not going to lie, I over complicated this one enormously when I first tried this, then I spent longer than I would care to admit trying to get it to store media on Amazon's S3 buckets. I'm not going to go into details on how to do that in here though. Sorry. The trick is, however, to use S3

So we have our Media Collection, let's import it into our seed file and hook it up, but before we do this you will need to create a local file for the images you wish to use.

I've done this within seed/media, so will look a bit like this:

Now, after running your script, you should see the logs and if everything is set up properly then you will see your images appear in your Amazon S3 Bucket and their reference IDs in your database in the Media collection.

As a bonus, why not try modelling, creating and storing different types of media like gifs, documents, videos and music? It's a good exercise to practice what you've learned.

Every app needs users, both administrative (provided by Payload) and business-use (created by us). Here's a simple User Collection; yours will probably look much different

Once we have a User, we'll create our SuperAdmin user first; this just makes it easier for us to go into the app to check our progress

You can probably see where this is going, but its where we first get to use Faker!

When we run the script, we use the default user values (2 admin and 10 editors) to create 2 admins & 10 editors with fake names, emails, passwords (that we can actually use to log in as them), but also a Super Admin who's details stay the same and you can grant any executive privileges to should you choose to.

We now have Media and Users, so we can start making content. We'll start with the simpler Collection, Pages.

Pretty simple. The Media field will save the image itself in our bucket but the ID in Mongo and reference it in this collection.

However, since we want to generate Rich Text to mimic the Rich Text Editor with which I'm writing this post, we need to replicate its structure.

We could create another method within the class to handle this but we might as well utilize inheritance.

In this example, I've created two more classes:

In a nutshell, we randomly generate arrays of Rich Text blocks in order (headers then lists then paragraphs etc) and then shuffle the array at the end using another helper method defined in the helper class.

Once you have your helpers, you can create the main methods. Each Page needs and author which we grab randomly from `this.users`

Also important to note that the way the methods are configured you can consistently create the same pages every time (eg About, Contact, Clients, whatever), as well as random ones. This is useful if you have both static pages and dynamic pages.

Excellent! Running your script now should drop then populate Media, Users and Pages with relations to each other.

Since these are very simple I'm going to write them up together. Basically, we want to include these for our Post documents. 

In my example, a Category would be more general, like Development, Testing or Deployment, whereas a Tag would be more specific, like AWS, Payload, Docker, Typescript or Jest. Again, just an example. Go crazy.

Cool. Now for the seeding method. I chose to create the same tags each time but you're under no obligation to do that. Fill your boots with Faker data!

Run your script to check it works. If it does, awesome. If not then put on your debugger hat. This post doesn't have comments. Sorry

Finally onto the main event: creating a Post that utilizes our Media, Users, Categories and Tags!

A very rough seed file with 5 related collections, Media in S3, Rich Text maker and Faker and a smidge of inheritance. No doubt some people will look at this with horror but who cares - its just a rough guide to help you with the general direction. Hope you enjoyed it!

This will be a short post because I'm tired:

At Antler we've recently implemented a new pattern for creating Playwright test ID selectors dynamically 

Creating dynamic test IDs for Jest and Playwright

 which I know is a bit of a Playwright anti-pattern but we only have the budget to use Playwright as smoke tests rather than fully-fledged E2E tests so time is money!

Furthermore, given that both the front-end and back-end teams have their own Playwright use-cases, we needed an easy way to get all the IDs on a page and ideally make them type-safe both for regressive tests and intellisense.

As a disclaimer, we use NextJS for our front-end so simply scraping the source files doesn't work:

The TLDR of this is function is that takes in the HTML as a string (eg "<body>/*...*/</body>"), uses a regex matcher to find all occurences of our selector (`data-playwright-id="<the_id_we_want>"`), and then parse them in 4 ways:

Ok we have the script, awesome, but right now it's a manual process. We're going to implement this into a separate Playwright script that will crawl, scrape, store and parse all of our selectors.

You clearly don't need all of them but having the options is useful. In our case, since we want these typed for a better dev experience, we want to take the .ts files and create declaration files for them. We can do this by using the `typescript` package to emit only declaration files:

And there it is - when you run the script "yarn playwright:scrape" it will run playwright with a specific config which targets a specific directory which runs no tests, but instead runs our scraping script for each page that gets rendered. Pretty neat. After Playwright has run it will convert those files to declaration files so you can use intellisense in your tests like so: