DEV Community: Obinna Ekwuno

Lawful Agents, Part 1: Your agent is reading an API that was never written for it

Obinna Ekwuno — Wed, 21 Oct 2026 15:22:11 +0000

If you have ever pointed an agent at an enterprise API, you will know how it goes. The response comes back five levels deep, the model spends half its context working out where the manager's name lives, it retries when a field is not where it expected, and eventually it fills the gap with something it made up. Then you spend the afternoon wondering whether the problem is your prompt.

It usually is not your prompt. Most enterprise APIs were designed for a developer who reads the documentation once and writes code against it. Your agent does not get that luxury. It meets the API fresh on every call and has to work it out from whatever is in front of it.

This series is about building agents you can actually trust with enterprise systems, the kind that stay inside the rules of the organisation they work for. I am starting with the tools those agents call, using Workday's Agent-Ready MCP tools, because how a tool is designed decides most of what happens next.

What changes when the tool is written for the model

Agent-Ready tools cover areas such as Workforce, Financials, Talent, Payroll and Recruiting, and three choices make them behave differently from the APIs you are used to.

The first is that the schemas are flat. Instead of something like this:

{
  "supervisoryOrganization": {
    "id": "SO-1180",
    "manager": { "worker": { "...": "..." } }
  }
}

your agent gets one layer of clearly named fields. Less structure to navigate means fewer tokens spent parsing, faster responses and far less room for invention.

The second is that every tool describes itself. Each one carries metadata about what it does and what each parameter expects, so when an agent sends "Oct 1" to a field that wants an ISO-8601 date, the error gives it enough to fix the value on the next attempt instead of guessing again. I have written before about APIs that already know what went wrong, and this is that idea applied to a reader that never gets tired of retrying.

The third is that they speak a standard. The tools follow the MCP JSON-RPC 2.0 specification behind a single endpoint for your tenant:

https://{agentGatewayRegionEndpoint}/{tenantName}/mcp

Your agent connects once, and the model handles tool selection and call syntax from there.

Bring your own agent

This is the bit I find most interesting as a developer, because you do not have to build inside Workday to use any of this. If your agent lives in Claude, Cursor, Copilot Studio or Google Agentspace, it can call the same tools a Workday Custom Agent does. The difference is that you do the registration yourself.

A Custom Agent built in Workday discovers and registers its tools automatically when you save and deploy. A third-party agent has to be registered in the Agent System of Record (ASOR) first, with the tools it is allowed to use listed in its agent definition. Here is a trimmed version of the documented example, a preferred name change agent built on Google Agentspace:

{
  "name": "Preferred Name Change Agent",
  "provider": "SELF-BUILT",
  "platform": "GOOGLE_AGENTSPACE",
  "workdayConfig": [{
    "skillId": "preferred_name_change",
    "executionMode": { "id": "Mode=Delegate" },
    "workdayResources": [
      { "tool_name": "create_worker_preferred_name_change", "agent_resource": { "id": "..." } },
      { "tool_name": "list_name_titles", "agent_resource": { "id": "..." } },
      { "tool_name": "list_name_salutations", "agent_resource": { "id": "..." } },
      { "tool_name": "list_hereditary_name_suffixes", "agent_resource": { "id": "..." } },
      { "tool_name": "list_social_name_suffixes", "agent_resource": { "id": "..." } }
    ]
  }]
}

Registering the agent gives you an Agent System User (ASU) token. Authentication is OAuth 2.1 with PKCE only, which most agent platforms and MCP clients already handle natively, so in practice connecting looks like adding any other remote MCP server to your client of choice and pointing it at your tenant's endpoint.

You might be wondering why that example lists five tools when the agent only does one thing. That is down to prompt tools, which are worth understanding before you register anything.

The tool type that will catch you out

You will see three kinds of tool in the catalogue.

Type	What it does
Basic	Reads data
Advanced	Writes data
Prompt	Reads the valid options a write tool needs

Lots of Workday fields only accept a value from a predefined list, and a write tool needs the Workday ID (WID) of the right option rather than a string the model came up with. So before create_worker_preferred_name_change can submit anything, the agent calls the four prompt tools to fetch valid titles, salutations and suffixes, picks the right one and passes its WID along.

The catch is that every prompt tool a write depends on has to be in your agent definition too. Leave one out and the write cannot complete. The MCP Explorer lists the required prompt tools in each tool's Details section, so check there before you register.

Finding the tools you need

The MCP Explorer on developer.workday.com is where I would start. You can filter by type, read each tool's description and schema, and copy the WIDs you need.

If you would rather do this from a script or a build pipeline, the ASOR Agent Resource Search API gives you the same catalogue programmatically:

curl "https://us.agent.workday.com/asor/agentResourceSearch/v1?searchString=time%20off&toolType=AGENT_READY&protocol=MCP" \
  -H "Authorization: Bearer [token]"

searchString is required and matches partial, case-insensitive names. You can narrow results with toolType (AGENT_READY for native tools, or AGENT to find Workday agents your agent can call as tools), operationType (CREATE, PATCH or VIEW) and protocol=MCP. Each result includes the wid that goes into agent_resource.id when you register. You will need Extend Professional and a token for a user with the Setup: Agents domain, and depending on your subscription agreement the API may need enabling first.

Guardrails you do not have to write

Good tools fix the performance problem. What gets an agent past a security review is knowing what stops it doing something it should not, and here none of that lives in your prompt.

The question	The answer
Who is it acting as?	Its own Agent System User, authenticated with OAuth 2.1 and PKCE
Whose data can it see?	In delegate mode, never more than the person it is acting for
What can it call?	Only the tools in its agent definition, with security set per skill and per tool

That last row is the one I would point a security team at. You are not asking the model to please stay in its lane. The platform enforces identity, permissions and an explicit allowlist, whether the agent was built in Workday or in your own stack.

Build for change, not for a version

Read this section twice before you ship anything. Agent-Ready tools are one continuous, unversioned surface that Workday keeps optimising for how models use it. Names, schemas, field names and descriptions can change without notice, and the MCP Explorer updates every Tuesday with a CSV change log you can download.

That is a fair trade for tools that keep getting better for agents, but it changes how you build:

Use them from agents only. Hard-coded UIs and standard integrations on these tools are not permitted, and anything that depends on a specific tool name, field or structure will eventually break.
Keep tool names out of your prompts and let the agent discover tools at runtime from their descriptions.
Know what counts as breaking. Workday keeps it narrow: a tool removed with no replacement, a validation you cannot satisfy, or a security change that takes away access you had. Those come with advance notice. Renames and automatic migrations do not.
Expect your results to vary. The tools themselves run deterministically, but the model, client, instructions and prompt around them do not.
Watch for long tool names, which some MCP hosts fail on. If one causes trouble, drop it from your registration and report it.

It also helps to know the limits up front, which are 2,000 concurrent requests, with a refresh rate and burst limit of 500 requests each. The server supports MCP protocol versions 2024-11-05, 2025-03-26, 2025-06-18 and 2025-11-25, so most current clients will connect without any fuss.

Start here

If you want to try this yourself, join the Workday Developer Program to get access to the MCP Explorer, the docs and a community of people building agents on Workday.

Try this with your own agent:

Browse the MCP Explorer and pick one read tool and one write tool.
Note the WIDs, including every prompt tool the write needs.
Register your agent in ASOR with those tools in its definition.
Connect your MCP client to your tenant's endpoint and ask it to do something useful.

The interesting part of building enterprise agents was never getting the model to call a tool. It is making sure the tool tells the model enough to get it right, and that the platform refuses when the model gets it wrong.

In Part 2, I look at what happens when the job does not stop at Workday's edge, and how Custom Agent Actions let you turn your own workflows and third-party services into tools that carry the same guardrails.

Your Workday orchestration in VS Code, drawn the way the builder draws it

Obinna Ekwuno — Wed, 30 Sep 2026 14:05:22 +0000

NOTE: This is a read-only viewer. It renders exported files for reference and clarity. Orchestration Builder remains the source of truth for what will or won't validate or compile the viewer never edits anything.

Workday Orchestration Builder is a browser-based, low-code drag-and-drop tool on the Workday Developer Site used to create real-time, event-driven workflows and integrations. You get a trigger at the top, steps flowing downward, branches fanning out, loops with their bodies tucked inside, and the whole thing validates and compiles as you go. Then you export the project from your app, open the folder in VS Code, click any .orchestration file, and all of that visual clarity collapses into one line.

Not one object —one line —thousands of characters long, every value wrapped in a _type and _value envelope, and your editor dutifully renders it as an infinite horizontal scroll. You know there is a flow in there. You built it. You just cannot see it from here.

Workday already bridges part of this with Local Disk Sync, which saves your app to a local folder and keeps the builder and disk in step. That gets the files into git. It doesn't help when you're reading a colleague's branch, reviewing a pull request, or working somewhere Chrome isn't open.

The builder is where a flow gets made, and the repo is where it gets reviewed, versioned and shared, and I wanted the second place to be as readable as the first.

So I built a small extension that carries the builder's picture of a flow into the editor. It is called Orchestrate Flow Viewer, it works in VS Code and Cursor, and it renders .orchestration and .suborchestration files as interactive flow diagrams drawn the way the builder draws them.

This post is the what, the why, and enough of the how that you could build something similar yourself.

What it does

Any Workday app can be exported so a developer can see its underlying folder structure. Choose any app that has an orchestration in it, export it, and open it up using this tool (any app with appManifest.json and an orchestration/ directory).

Click a flow file, and you get the same picture the builder would show you, right there in your editor. The Start or trigger step sits at the top and the steps flow downward along a spine.

Branch on Conditions arms fan out side by side, in the same left to right order the builder evaluates them under little white pills and reconverges at a join. When it comes to Loop bodies, they are nested under their loop card behind a chevron you can collapse.

Error handlers are the one place I deliberately depart from the builder. There, local and global handlers open on their own canvas. A static diagram can't click through, so the viewer pulls them inline: the global handler as a detached region below the main flow, and local handlers as a badge on the step that owns them, borrowing the builder's lightning bolt icon.

If you can read a flow in Orchestration Builder, you can read it here, because the visual language is the same on purpose.

Selecting any step opens a details panel loaded with context straight from the builder:

Step Context: Review assignments, expressions, branch conditions, loop iterators, add integration message severity, and store-document settings.
Resource Resolution: Inspect CSV columns resolved directly from the flow's resources alongside suborchestration parameters.
Subflow Navigation: Click Call Subflow cards to instantly jump to target suborchestrations across your workspace without waiting for page loads.
Developer Environment Tools: Enjoy full editor support with pan, zoom, a minimap, live re-rendering on edit, theme matching, and a toggle for pretty-printed raw JSON.

Why a viewer, and why read-only

Orchestration Builder remains the place to create orchestrations—this project doesn't change that. But once you download the source, you're dealing with files. And files belong where developers already work: in repositories, branches, and pull requests ready for review.

As Workday expands its developer platform, it brings an expectation that you can work in standard development environments. You build in Orchestrate, then review, version, and share in VS Code or GitHub just like any other code you ship.

However, the file reads like it was written for the compiler, not for you. The IntelliJ plugin takes the same view, treating the orchestration folder as read-only and pointing you back to Orchestration Builder to edit. The viewer follows that convention.

The goal is intentionally focused: make exported files readable right where they live—nothing more. It isn't a secondary editor or a replacement for the builder. The viewer simply renders what is in the file, which doesn't guarantee the flow will validate or compile.

What the file knows, and what the builder knows

To reconstruct the builder's visual layout from an exported file, I first examined the underlying file structure. Two key characteristics stood out immediately. First, every single value is wrapped inside a type envelope, as shown when pretty-printing a flow:

{
  "_type": "CreateValues",
  "_value": {
    "name": { "_type": "String", "_value": "InputFile" },
    "isDisabled": { "_type": "Boolean", "_value": false },
    "errorHandler": {
      "_type": ["Opt", "ErrorHandler"],
      "_value": { "_type": "ErrorHandler", "_value": { "…": "…" } }
    }
  }
}

Taking errorHandler as an example, it is represented as an ["Opt", "ErrorHandler"] wrapper enclosing another inner wrapper. Optional fields effectively create nested envelopes, where an absent optional evaluates to an envelope wrapping null. Furthermore, certain exporter versions emit un-wrapped bare objects for group bodies, requiring the parser to handle both representation styles seamlessly.

The second, more subtle realization influenced the entire architectural approach: diagram information exists within the Orchestration Builder interface rather than the source file itself. The exported file stores structural data rather than graphical layout—omitting explicit edges, node identifiers, or spatial coordinates. Execution sequence is inferred from array ordering, branching is established through element containment, and loop bodies are structured as nested lists. While this compact format is optimized for platform execution and compilation, re-creating the builder's interactive diagram within VS Code required translating these structural semantics back into a visual node graph.

This led to a multi-stage pipeline architecture designed to make implicit relationships explicit, enforcing a clear separation of concerns at each phase:

.orchestration file (text)
        │
        ▼
  src/core/parse.ts      unwrap the envelopes → typed FlowModel
        │
        ▼
  src/core/graph.ts      synthesise nodes and edges → FlowGraph
        │
        ▼
  src/core/layout.ts     assign x/y/w/h to every node
        │
        ▼
  src/webview/…          render with React Flow inside VS Code

All components in src/core/ consist of pure TypeScript without any VS Code API dependencies. Consequently, the core pipeline can execute in standalone Vitest suites or standard browser environments. The VS Code extension itself acts as a lightweight wrapper around this core logic—a design boundary that significantly simplified testing and maintenance.

Teach the parser the envelope, once

Before building the parser, I established a clear vocabulary for interpreting the format: eight utility functions in src/core/unwrap.ts designed to handle any output variation from the exporter. The core work is handled by peel:

/**
 * Peel wrapper-of-wrapper layers (e.g. Opt<ErrorHandler> whose _value is the
 * wrapped ErrorHandler) down to the innermost wrapper. A null Opt stays put,
 * so callers see unwrap(peel(v)) === null for absent optionals.
 */
export function peel(v: unknown): unknown {
  let cur = v;
  while (isWrapped(cur) && isWrapped(cur._value)) {
    cur = cur._value;
  }
  return cur;
}

Building on this foundation are field, str, bool, num, list, and record. Each helper safely evaluates wrapped or bare objects, returning undefined or an empty list for unexpected shapes instead of throwing an error. Routing all property access through these utilities encapsulates envelope parsing entirely. This enforces a core architectural rule across the project: malformed input degrades gracefully rather than crashing the application.

Assume Workday will ship something you have not seen

Workday releases new Orchestrate components regularly. This means the parser will inevitably encounter step types it hasn't seen before—and it will meet them in real user projects, not just in test fixtures. The default case of parseStep gracefully handles these situations using a two-tiered approach:

default: {
  // Unseen component types must never break the diagram. If the payload
  // carries a body of child steps (loop-like components such as Batch
  // Loop / Join Loop), render it as a container so the children survive.
  const groupRaw = field(raw, 'group');
  const hasGroup = list(field(groupRaw, 'nodes')).length > 0;
  const directNodes = list(field(raw, 'nodes'));
  if (hasGroup || directNodes.length > 0) {
    warnings.push(`Unknown container type "${rawType}" (${id}) — rendered generically.`);
    const group = hasGroup
      ? parseGroup(groupRaw, childPath, warnings)
      : { id, name, steps: directNodes.map((n) => parseStep(n, childPath, warnings)) };
    return { ...base, kind: 'genericContainer', group, entries: leafEntries(raw, new Set(['group', 'nodes'])) };
  }
  warnings.push(`Unknown step type "${rawType}" (${id}) — rendered generically.`);
  return { ...base, kind: 'generic', entries: leafEntries(raw) };
}

If a component I haven't written a parser for contains child steps, it is parsed as a generic container. This allows any nested steps to be parsed normally and displayed as functional cards. Any other unrecognized structure becomes a generic step, displaying a raw dump of its fields in the details panel for complete visibility. Both paths increment a warning counter in the toolbar. While an unseen component might lack a custom icon, it will never break the visual diagram.

Why I wrote 150 lines instead of using dagre

When it came to the layout stage, using an existing graph library like Dagre or ELK seemed like the obvious choice. However, I decided to build a custom solution instead. General-purpose layout engines tend to produce organic structures that shift dynamically as the graph changes. In contrast, the Orchestration Builder interface relies on a consistent, highly predictable layout: a single vertical spine flanked by neatly aligned branch arms.

Branch order matters too, Orchestrate evaluates Branch on Conditions arms left to right and runs the first that's true, so a layout engine that reorders arms is misreporting execution order. A custom algorithm guarantees this exact structure every time—ensuring identical input always yields identical output.

layoutGraph operates using two recursive tree passes. The first pass measures bottom-up, memoizing each subtree's bounding box so branch arms know their required width before placement. The second pass places elements top-down, centering items along the spine and advancing a y-cursor. Branch arms are centered as rows beneath their root node, and joins are placed at the measured bottom so all paths reconverge seamlessly.

Centralizing node dimensions in a single lookup table makes global visual adjustments simple:

const SIZES: Record<NodeKind, { w: number; h: number }> = {
  trigger: { w: 300, h: 118 },
  end: { w: 220, h: 64 },
  step: { w: 280, h: 84 },
  branchRoot: { w: 280, h: 84 },
  globalError: { w: 280, h: 84 },
  pill: { w: 132, h: 36 },
  expander: { w: 26, h: 26 },
  join: { w: 10, h: 10 },
};

Deterministic layout also makes the visual structure fully unit-testable. For instance, a key test suite iterates through every node pair across all test fixtures to verify that no elements overlap:

it("has no overlapping nodes", () => {
  for (let i = 0; i < graph.nodes.length; i++) {
    for (let j = i + 1; j < graph.nodes.length; j++) {
      const a = graph.nodes[i];
      const b = graph.nodes[j];
      expect(overlaps(a, b), `${a.id} overlaps ${b.id}`).toBe(false);
    }
  }
});

If a measurement pass undercounts a subtree, overlapping cards immediately fail the test with the precise node IDs responsible. This test caught several real layout bugs during development—an advantage made possible solely by deterministic positioning, which third-party layout engines cannot reliably guarantee.

The rest is plumbing

The webview component renders via React Flow. Since the layout phase computes absolute node positions in advance, the webview primarily maps graph nodes directly to locked React Flow elements—ideal for a read-only viewer.

Edges use right-angle elbow connectors rather than bezier curves, categorized by function so horizontal segments route exactly where the Orchestration Builder would place them. Furthermore, because all color styles leverage VS Code's CSS variables, light and dark themes work seamlessly out of the box without requiring custom styling code.

On the extension side, a CustomTextEditorProvider allows VS Code to handle document state, text editing, and file watching natively, leaving the extension focused entirely on rendering. Communication between the host and webview relies on a lightweight, typed protocol. Incoming edits stream in with debouncing so side-by-side editing won't trigger heavy re-layouts on every keystroke. Additionally, a workspace index scans orchestration IDs, enabling Call Suborchestration cards to display target names and open corresponding files on click.

Key Takeaways

If you're building a similar extension or tool, here are three core principles worth applying:

Identify the core problem first: The goal was never just to render raw JSON, but rather to bring Orchestration Builder's visual clarity directly into the editor environment. Defining this goal made designing the processing pipeline straightforward.

Keep core logic decoupled: Avoiding VS Code API dependencies in the core pipeline enabled comprehensive unit testing against exported files, allowed fast diagram iteration in a standalone browser harness, and minimized webview complexity.

Design for future schema changes: Implementing a two-tiered fallback mechanism alongside a warning counter ensures that newly released Workday components render gracefully without breaking the layout achieved in about thirty lines of code.

Start here

Getting started takes only a couple of minutes:

Install the extension: Orchestrate Flow Viewer on VS Code Marketplace
Open a downloaded: Select any project folder containing an appManifest.json and an orchestration/ directory.
View the flow: Click any flow file and toggle the JSON view once to compare the formatted diagram against raw source data.

The source code is available on GitHub under the MIT license at https://github.com/Ekwuno/workday-orchestrate-viewer . Upcoming roadmap features include breadcrumb navigation for subflow drill-ins and PNG/SVG export options. If you encounter rendering issues with an exported flow, please open an issue in the repo

Orchestration Builder has always understood your flow's visual layout now your editor does too. Head to developer.workday.com and join the Workday Developer Program, where you'll find the guides, the community and everything you need to start building.

TIL: How to make a Synced Sandbox from a GitHub repository

Obinna Ekwuno — Thu, 23 Feb 2023 15:06:28 +0000

"Some features work like magic. Some features are just Magic!" - Some human.

Today I learned about a really helpful feature on CodeSandbox that automatically allows you to create Sandboxes that stay synced with changes you make to your GitHub repositories.

TIL means Today I learned. 😉

Synced sandboxes

From my understanding, Synced sandboxes are sandboxes that stay up to date with the latest changes you have pushed to a GitHub project using your .git file.

Their main advantage is that they allow you to create sandboxes from specific sub-folders within your GitHub projects without importing the whole repo.

Make a Synced Sandbox in CodeSandbox

First, open your project on GitHub and then edit the URL to start with codesandbox.io/p/sandbox/ prefix before the github.com the remove .com from github.com.

For example, let's use the demo project from my last blog post on Content collection in Astro.

The GitHub URL: https://github.com/Ekwuno/content-collecttion-api-example will become
https://codesandbox.io/p/sandbox/github/Ekwuno/content-collecttion-api-example

Why does this need to exist?

When changes are made to your GitHub projects or your example subfolders, you have to do the stressful task of updating all other replicas across platforms, but with synced sandboxes, they all stay up to date because they are "synced" to the source.

Once you push a change to GitHub, your sandbox also has those changes.

Use case for Open source projects.

Another use case I see is for Open-source projects that have example folders. Most frameworks have a repo with example folders which are usually sub-folders that get harder to maintain. By making these example folders synced sandboxes, each update is added automatically, allowing maintainers or contributors to share specific folders as sandboxes so they can be viewed as individual projects.

Use case for Embedding Cloud sandbox to docs.

The final use case I see for this feature is embedding your GitHub repository in the documentation and ensuring it is always up to date. So when people come to docs, they can create sandboxes from the embeds.

I recently made one of these for a project Joe Previte made and now whenever Joe makes an update, this sandbox I made gets the changes.

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

That's all, folks!

How to use content collection in Astro.

Obinna Ekwuno — Mon, 06 Feb 2023 16:38:50 +0000

In case you missed it, Astro launched 2.0 with a couple of exciting announcements, one of which is the new Content collection API with Type-safety powered by Zod.

In a previous post, I wrote a summary of What's new in Astro 2.0; you can check it out for more information.

This post will look at creating Content collections and how you can start building and sourcing content in your Astro application.

We will be doing so by building a simple newsletter application, exploring creating a collection, querying the collection in components and creating routes for each markdown file in the collection.

Project setup

To follow the project in the blogpost, you can fork my content collection example project on Codesandbox. Create a fork, and you are good to go.

Pull the repo from GitHub and set up if you prefer to do this locally.

The parts that are covered is the Content/, Pages/newsletter folders. The file structure looks like and t

/
├── public/
│   └── favicon.svg
├── src/
│   ├── components/
│   │   └── Card.astro
│   ├── content/
│   │   └── newsletter
│   │       ├── post-1.md
│   │       └── post-2.md
|   ├── config.ts
│   ├── layouts/
│   │   └── Layout.astro
│   └── pages/
│       ├── newsletter
│       │   ├── [slug].astro
│       └── index.astro
└── package.json

Setting up Content Collections in Astro

A content collection is a group of .mdx or .md files that are created under the src/content folder in Astro. The content files are type-safe and allow you to group your content in a schema and type-safe way. Once you have a collection, you can start querying your content using Astro’s built-in Content APIs.

Define collection schema

First, create a config.ts file in the src/content folder, which is the config file where you define the "collections" for your project. We describe the frontmatter schema in this file and use Zod to define types.

From the code block below, you can notice that we define the schema with some types. Doing so ensures that when we create new .md or .mdx files, the frontmatter is type-safe, and we get the benefits of Typescript in markdown.

import { z, defineCollection } from "astro:content";

// Define a collection of newsletter posts
const newsletterCollection = defineCollection({
// Define the schema 
    schema: z.object({
        title: z.string().max(100),
        date: z.date(),
        categories: z.array(z.string()),
        summary: z.string(),
        image: z.string().optional(), //Image can be optional
    })
});

// Export
export const collections = {
    //  collectionName: collection
    newsletter: newsletterCollection,
};

Creating Markdown content in Astro

Since we are creating content collections, the markdown files must follow a "collection" type format. So in the src/content folder, create a newsletter folder this is where we add markdown files and inside those files add the frontmatter, following the schema format that is was defined.

Under the newsletter folder create a post-1.md and then define the frontmatter with respect to the schema

---
title: "Newsletter Post 1"
date: 2019-01-01T00:00:00.000Z
categories: [Newsletter, News]
summary: "This is the first newsletter post."
---
# Newsletter Post 1

// Content

The frontmatter is type-safe, so if you add any field that isn't defined in the schema, you will get a prompt to fix the error. Thankfully Astro has very helpful error messages to prompt. Also, notice how no image is defined because, in the schema, it is marked as optional.

Importing Content collections to components

Now that you have defined the schema and have your first post up. You can pull your content data using the getCollection from astro:content.

Then pass your collection name into the getCollection function. Doing so will give you an array that you can map through and display in a component.

You might need to restart your dev server after importing so that astro:content can be accessed.

import { getCollection } from 'astro:content';
const newsletters = await getCollection('newsletter');

// ...

{ newsletters.map((newsletter) => {
    return (
        <Card
         href={`/newsletter/${newsletter.slug}`}
         title={newsletter.data.title}
         body={newsletter.data.summary}/>
        )
    })
}

Notice that the href for the newsletter cards opens up a path /newsletter/${newsletter.slug}. This is because, in Astro, all pages are created under the pages folder so, we create a newsletter folder under pages to make routes for each post.

You can make multiple routes for each collection that you have.

Generate Pages for Content collections

If you are familiar with creating dynamic routes, they are often depicted with [] and have an identifier to create the routes based on the identifier.
For example, it can be making each route based on the id:[name.id] or on the folder's name [Professions.name].

To create a new page for each of the newsletter entries under the Pages folder, create newsletters/[slug].astro; this will create a new page for each post.

Of course, you can also define custom slugs for your files, but we will stick with the generated ones.

First, get the collection; you will use the getCollection function again.

import { getCollection } from "astro:content";

Then, because we want to create paths from these collections at build time, we make a function getStaticPaths. In this function, we will pass the newsletter collection into getCollection and await the response.

This response is then mapped out to create a slug for each post at build time, the params Object shows what file is rendered, as seen below:


// This function gets called at build time and generates the paths from the content folder
export async function getStaticPaths() {
    // Define the colection you are creating pages for
    const allNewsletters = await getCollection("newsletter");

    return allNewsletters.map((newsletter) => {
        return {
            params: {slug: newsletter.slug},
    // 
            props:{newsletter},
        };
    });
}

Access props and rendering markdown for Content collections.

Now that we have defined the newsletter, we would need to access the props in this particular component, and we can do that with Astro.props to typecast this even further add a
{CollectionEntry<>} type and pass in newsletter as seen below:

---
import {CollectionEntry, getCollection } from "astro:content";
//.. 

// Access the props in this component 
const {newsletter} = Astro.props as {newsletter: CollectionEntry<"newsletter">};
const {Content} = await newsletter.render();
---

To get the actual content from the post-1.md file, call the render function pass in the Content.

We can now render the content like so:

<main>
    <h1>{newsletter.data.title}</h1>
    <p>Category: {newsletter.data.categories.join(',')}</p>
    <Content />
    <p>
    <a href="/">Back to previous newsletters</a>
</p>
</main>

Learn more

Astro's content collection API allows for so flexibility and type-safety when it comes to handling data. There is also a guide for migrating from File-based routing if you want to update your projects.

To get started with this example project, you can create a fork of my Content-collection API project on CodeSandbox. Happy coding 👋🏾

What's new in Astro 2.0?

Obinna Ekwuno — Wed, 25 Jan 2023 16:08:31 +0000

Astro 1.0 introduced developers to a way of building applications optimised to reduce excess Javascript in an application by introducing us to Astro Islands, representing a paradigm shift for frontend web architecture.

This shift allows people to build static Pages and implement "Islands" of dynamic behaviour using frameworks you were already familiar with, like React, Vue, and Preact ...

This shift brought ASTROnomical (Pun intended) improvements to the performance of your application as the Unused JavaScript got replaced with lightweight HTML, which meant faster loads and time-to-interactive (TTI).

The use case of Astro spans E-commerce and blogs. As you can imagine, the list keeps growing.

So... Astro 2.0?

Collection API

Since a lot of the content coming into websites these days are static coming from a content management system (CMS) or Markdown or MDX, Astro has added a Collection API which allows you to manage collections of extended markdown files in a Type-safe way!

If you are familiar with Typescript's data inference, you can now get that in Astro powered by zod, which is a Typescript validation library.The src/content directory allows you to group together markdown files and access them from within your application.

Learn more about the Content API in the documentation

Hybrid rendering..

When building applications you often have to make the decision between static (SSG) and server (SSR) build output.

What if... ? What if you could enable server side rendering and static site generation on a per route bases??

Well now you can with Astro 2.0!! This means Improve render performance of popular pages and performance improvements with builds.

You can now pre-render certain pages without giving up your
deployed server. Pre-rendering builds pages ahead-of-time so
that all of those requests load instantly.

Improved Error messaging

Astro 2.0 provides better error messaging, you know.. the type that is helpful and doesn't make you want to do this:

It's so much better, because it points out exactly what's wrong.

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

Other Improvements

There have been improvements to the Hot module reload(HMR) of Astro, and it also now supports some Vite 4.0 improvements.

Astro also officially launch the new Public Roadmap for Astro. So now you can see all the things the team is up to!

You can start testing these new features today by running npm i astro@latest to upgrade an existing project. If you don't have an existing project, you can start a new project locally or on an Online development environment like Codesandbox.

Codesandbox has automatic Language syntax support for Astro and is a really seemless way to build applications without setting things up locally as it is powered by micro VMs

Check out the Astro starter running 2.0 already: https://codesandbox.io/p/sandbox/astro-j1qiqf

In a follow up blog post I'll be sharing a project using Astro 2.0!

Happy coding! 🎉

Auditing for accessibility with Evinced

Obinna Ekwuno — Wed, 03 Feb 2021 18:45:39 +0000

Again, the topic for today is accessibility. I know sometimes when you hear about this your eyes roll to the back of your head. Maybe. because the process of testing for this can be a bit too long or stressful.

Another reason might be you don't even know exactly what you are looking for. Now you have 50 tabs open looking for the answer to a "few" (37 heading to 60) accessibility warnings.

I am going, to be frank with you, auditing for accessibility defects is hard. Even harder when you don't know if the bug you are fixing exists in one place or does it span your app. -- This is another horror story.

Where does it all end?

I spent a couple of weeks testing out a new site scanner feature on a web service called Evinced. Evinced provides a way to pinpoint accessibility defects in a site by allowing the algorithm to crawl all the pages (or selected pages) on your website and scan for pages that have accessibility debts

Evinced has multiple tools for auditing accessibility, you can check them out on the products page.

The thing I love about this tool's site scanner feature is how it points out the specific problem and also redirects you to a glossary where you can learn more about the error it picked up and even examples.

Too much talk show me a demo!

I used this tool to test out some websites that I had been curious to know how they'd perform. The first site I tested was my personal site of course!

Now my personal site has an accessibility lighthouse score of 84, I set some color-contrast errors to see if Evinced would pick it up.

Most of these accessibility errors are in a subdomain of my website so Let's see how this plays out.

Step 1: Go to https://app.evinced.com/, you will be directed to apply for the free Community Service or Enterprise Free Trial for the Site Scanner, and then log in.

When that is done you'll see the modal below, then proceed to put your site URL in the property input box

Step 2: Allow the site scanner to crawl and scan your site and wait for the magic.

When the scan is over, you can see that it has gone through every part of your site (or the pages specified) and picked up all the accessibility errors, and even provides you with a break down of these errors

How does this help me fix it?

My 48 counts of violations for my website can be broken down by Evinced into components, that's really helpful because I can actually tell what's going on and where it is going on.

What this shows me is the exact problem and If I go into developer tools and checked the component I can fix it in chrome and that automatically reflects in my codebase

Conclusion and feedback.

I only tested this on my site because I created the accessibility errors and I wanted to see if the tool would pick it up.

However, a progress bar for the crawling and scanning process would be great I wasn’t sure when these processes finished because I just left the site and did something else.

At the end of the day, I am happy that more tools that aid and automate the process of accessibility exist.

Gatsby Cloud and Gatsby open source aren't mutually exclusive. Here's why I think so.

Obinna Ekwuno — Mon, 02 Nov 2020 21:54:13 +0000

Now I know, I work at Gatsby. I am supposed to say "good" things about Gatsby -- but here's the thing. Before anything, I am a developer and I care about my community.

I have spent a couple of days asking a lot of questions about how our community views the Cloud offering of Gatsby. Most of the comments seem to view it as Gatsby's "money maker",

Being open-source while also making a profit as a business seems to be a conflict in some minds. When open source starts to get involved with money, if not put in the proper context it can be seen as !Open-source (Not open-source, pardon me I couldn't help it. )

Here's what it actually is.

Gatsby Cloud, simply put, is an optimization tool for sites Gatsby built with the open-source framework. It will improve how fast your Gatsby sites are built and also offers you more optimizations as your sites grow.

It's like playing God of War on a PS4, for example. In the beginning, you have only a simple axe. But as you go further into the game you unlock pretty awesome abilities -- and you pay for them with the coins you have collected along the way. (Yes! I am currently playing God of War 😅).

Gatsby was designed for front end devs to be able to assemble websites from modular services, each one having its own best-fit data source, using plugins to make it quick to build this way. This architecture means that a site built with Gatsby is fast anywhere it runs. But for a Gatsby site to be as fast as it is architected to be there needed to be customized cloud infrastructure.

My point is Gatsby Cloud wasn't built to just "make money for Gatsby" -- although users paying for the advanced features added to it will help pay the Engineers working full time on open source Gatsby (i.e me and my team). It was built as the arena for Gatsby sites to reach their true superpowers.

Gatsby Cloud is of course a cloud platform. This infrastructure costs money! But we support open source even in our Cloud platform: we will always have a free tier for personal projects. Because we want anybody using the open-source Gatsby framework to be able to experience the ideal place to build and deploy their projects. If you're a company using a lot of Cloud builds on a product you make money from well, then, of course, we would like for you to pay for your usage.

Now, with that in mind here's what you get from using Gatsby Cloud to build your Gatsby Sites for free:

100 Real-Time Edits/month
Standard Builds
Deploy Previews
Real-time CMS Previews
Lighthouse Reports
1 editor

In my opinion, this is pretty helpful for a free plan and if you're not running a really giant site or doing constant updating this is perfect.

Now the more advanced stuff like Incremental build, Site Access Control, extended real-time edits/month for larger themes, comes with the paid plans (which start at $19/Month 🤭). This is cool! But tbh these are things that big teams working on big projects would benefit from more.

In conclusion

Gatsby Cloud at its core is built to improve the workflow of the web developer using Gatsby open source, by providing a tool to build at blazing speed and also cut build times by 90% to <10sec. Check out willit.build which is a benchmark site that helps predict the build time of your site.

I hope this helps and also I am happy to hear your opinions about Gatsby Cloud. Would you use it? Anything I can help explain?

What do you think about GraphQL? Who's using it? Love it, hate it? Tell me why?

Obinna Ekwuno — Wed, 28 Oct 2020 20:39:32 +0000

My story with learning and using GraphQL is a bittersweet one, I went from "What does this button do?" to "WOOT WOOT"

Why did you start using GraphQL? If you don't why not?

This Filesystem API made my life easier.

Obinna Ekwuno — Sat, 10 Oct 2020 20:48:54 +0000

Building with static site generators is aimed at cutting off all the "difficult" parts and getting you started with serving content while using the same best practices and methods available.

We have a lot of them (Gatsby, Hugo, Jykll), some more straightforward than others, each solving a particular use case, and to be frank, I would rather not compare them based on usage but on the Use case. At the end of the day, it all boils down to what you are trying to do.

You see, the thing about abstraction is we have to know where to stop, as sometimes the solution might create a new problem. A problem that you have to solve.

Here's my experience with a particular problem.

Programmatically creating pages in Gatsby.

Now I love Gatsby, it makes a lot of things easier and in the process, it did open the door to a lot of other exciting things for me like GraphQL, and an API file called Gatsby-node, where a lot of my early pains came from.

The way Gatsby handles programmatically creating pages(which is a fancy way of saying, creating pages on demand by sourcing from a Content Management System) is in the following steps:

Source page via Slug in Gatsby-node.
Use the createPages API to create a page for each slug.
Resolve that in a template component path.
Create that Path and then source for all the other information using the slug as a unique identifier.

Looks something like this,

Sourcing using `createPages API`

Resolving in the Template directory

Sounds like a lot yes? Hence, the cover image of this blog post.

There are a lot of reasons why Gatsby uses GraphQL, the most common is to facilitate sourcing data from different places and getting the exact thing you need.

While this is a logical reason, this process isn’t as intuitive and sometimes might not be as straightforward as my steps make it seem.

What if there was a way to make this more interesting, with fewer lines of code?

Gatsby file system routes API

There is always a soul of good in things "evil" if people distill it out - Shakespeare

This was an answer to my WTF questions, an API built on top of the createPages API to replaces the above steps with a more intuitive approach. This is how it works:

use curly braces ({ }) in naming the file to signify dynamic URL segments that relate to a field within the node.
write your query as you would for a particular page.

You can leverage this feature by running

GATSBY_EXPERIMENTAL_ROUTING_APIS=1 gatsby develop

That's the END of this blog post.... (Joking)

Ok seriously, Here's an example, If you would query a file like so :

allProduct {
  nodes {
    id # Gatsby always queries for id
    name
  }
}

Then the file name in your pages directory would be src/pages/products/{Product.name}.js

Notice the pattern? Gatsby turns anything put into the pages folder to a route, so doing this automatically makes /products/{Product.name}.js to a route.

Here's what it turns the code block into:

Notice how the file name is in curly braces, that's about it.

Note: This File system Routes API is built on top of the createPages API so you will not have to refactor your existing applications 😉

In addition to the simplification, Gatsby automatically includes a gatsbyPath field on every model used by collection pages.

The gatsbyPath field must take an argument of the filePath it is trying to resolve. This is necessary because it’s possible that one model is used in multiple collection pages.

This is an example of what the gatsbyPath looks like in a query:

This feature is still experimental and as it gets built out I am sure it will create a more interesting way to query pages in Gatsby.

Wait there is more...

This file system API also helps with creating client-only route. Previously, to access dynamic content that isn’t known to Gatsby at build time,(Which is referred to as client-only routes) you would have to create a route with one or more dynamic segments to query data from a server in order to render your page.

For example, to show a user a personalized settings page, in order to edit a user, you might want a route like /user/:id to fetch the data for whatever id is passed into the URL. You can now use square brackets ([ ]) in the file path to mark any dynamic segments of the URL.

This means src/pages/users/[id].js would look like this /users/:id. Gatsby also supports splat routes, learn more about this in the documentation

Conclusion

There you have it, folks. I believe that with a few improvements to other pain points of Gatsby, some of the processes will be less stressful.

DEV Community: Obinna Ekwuno

Lawful Agents, Part 1: Your agent is reading an API that was never written for it

What changes when the tool is written for the model

Bring your own agent

The tool type that will catch you out

Finding the tools you need

Guardrails you do not have to write

Build for change, not for a version

Start here

Your Workday orchestration in VS Code, drawn the way the builder draws it

What it does

Why a viewer, and why read-only

What the file knows, and what the builder knows

Teach the parser the envelope, once

Why I wrote 150 lines instead of using dagre

The rest is plumbing

Key Takeaways

Start here

TIL: How to make a Synced Sandbox from a GitHub repository

Synced sandboxes

Make a Synced Sandbox in CodeSandbox

Why does this need to exist?

Use case for Open source projects.

Use case for Embedding Cloud sandbox to docs.

How to use content collection in Astro.

Project setup

Setting up Content Collections in Astro

Define collection schema

Creating Markdown content in Astro

Importing Content collections to components

Generate Pages for Content collections

Access props and rendering markdown for Content collections.

Learn more

What's new in Astro 2.0?

So... Astro 2.0?

Collection API

Hybrid rendering..

Improved Error messaging

Other Improvements

Auditing for accessibility with Evinced

Where does it all end?

Too much talk show me a demo!

How does this help me fix it?

Conclusion and feedback.

Gatsby Cloud and Gatsby open source aren't mutually exclusive. Here's why I think so.

Here's what it actually is.

In conclusion

What do you think about GraphQL? Who's using it? Love it, hate it? Tell me why?

This Filesystem API made my life easier.

Programmatically creating pages in Gatsby.

Sourcing using createPages API

Resolving in the Template directory

Gatsby file system routes API

Wait there is more...

Conclusion

Sourcing using `createPages API`