Coder Legion - Recent posts tagged sanity

Is there any way to make type conversion sexy? Nope

Tue, 20 Oct 2026 19:04:00 +0000

When converting a value of one type to another; There are conversions which never fail (ie int -> string). Some that can fail like string -> int, and then some lossy and implicit ones ( number -> int, int -> number)

How do we spell it in any of those situations?

My lean is to have a single tool with sane defaults. if you don't cover the error arm it wont compile and tell you why. That would look something like this:

<p>typed ${num} chars</> // No explicit cast needed, behaviour is dictated by the <p> parent

 <age:int | not=(int.parse(@txt))/> // "42" → 42, "abc" → not

type Guess:enum = { Yes, No }

<g:Guess | not=(Guess.parse(@txt))/>     // "Yes" → .Yes, "yes" → not

<p>${match @g {
    .Yes :> "yeppers",
    .No :> "nope",
    not :> "not a guess",
}}</p>

function qty(s: string) -> int {
    const n = int.parse(s)
    if (n is not) {
        return 0
    }
    return n                  // narrowed to int here
}

Lossy conversions are named, and round needs a tie mode

const avg = number.parse(@txt)          // number | not
// once narrowed:
floor(avg)                 // 3.7 → 3
ceil(avg)                  // 3.2 → 4
trunc(avg)                 // -3.7 → -3
round(avg, .HalfUp)        // 2.5 → 3
round(avg, .HalfEven)      // 2.5 → 2
round(avg)                 // error: name a tie mode

Into text: no conversion spelled, except where it's refused

<p>typed ${@txt.length} chars</p>          // ok: markup converts primitives
const msg = `typed ${@txt.length} chars`   // ok: a template is a text context
"typed " + @txt.length                     // error: + stays strict
label(@count)                              // error: int is not string
label(`${@count}`)                         // ok
<p>${@user}</p>                            // error: a struct has no one honest text form
fixed(@price, 2)                           // "3.14", from scrml:format

A bound number cell turns bad input into not

let <qty:int | not=0/>
<input type="text" bind:value=@qty/>      // "abc" writes not, never 0 or NaN


int.parse("42")       // 42
int.parse("-7")       // -7
int.parse(" 42")      // not   (no trimming)
int.parse("+42")      // not   (no plus sign)
int.parse("12px")     // not   (whole string or nothing)
int.parse("0x1F")     // not   (use scrml:math.parseInt(s, 16) for a radix)
int.parse("3.5")      // not   (tnumber, not an int)

number.parse("3.5")   // 3.5
number.parse("1e3")   // 1000
number.parse(".5")    // decided in the SPEC text; strict leans not

bool.parse("true")    // true
bool.parse("True")    // not
bool.parse("yes")     // not

Would anyone like to offer any criticism to this approach. Maybe a better idea.

I hope so

Ultra Bridge: Translating JAWS Keyboard Commands to NVDA with Sanity Context

Mon, 05 Oct 2026 18:59:50 +0000

This is a submission for the Sanity Challenge, Path One: Ship an Agent That Queries Real Content

What I Built

Ultra Bridge is an agent for screen reader users. You ask it things like "What is the NVDA equivalent of JAWS Insert+F7?" or "Which keys do different jobs in JAWS and NVDA?", and it answers from a Sanity dataset through Sanity Context MCP. Every answer says how well the underlying command is verified, so you know whether to trust it or check it yourself first.

I built it because I rely on a screen reader myself, and moving between JAWS and NVDA means relearning keys that look the same but are not. That gap costs real time and real confidence, and it is exactly the kind of problem structured content is good at closing. Ultra Bridge is part of the Ultra suite of accessible software I am building.

The reason it needs structured content: a keyword search can find a page that mentions both screen readers, but it cannot tell you which keys collide, which ones translate cleanly, or which ones simply do not exist yet on the other side. In Ultra Bridge an action ("show a list of all links") is separate from a command (the keys one screen reader uses for that action). Equivalents are found through the shared action, so a relationship question becomes one query instead of a guess.

This query lists every single letter key that exists in both screen readers but does a different job:

*[_type=="command" && screenReader->slug.current=="jaws" && context=="browse-mode"]{
  keys,
  "jawsAction": action->title,
  "nvdaMeansSomethingElse": *[_type=="command" && screenReader->slug.current=="nvda" && keys==^.keys && action._ref != ^.action._ref]{"action": action->title}
}[count(nvdaMeansSomethingElse)>0]

Against the seed data it returns six keys. R is "region" in JAWS and "radio button" in NVDA. Q is "main content" in JAWS and "block quote" in NVDA. A, O, S and D collide too. That is exactly the kind of thing that costs a person time when they switch, and exactly the kind of question a keyword search cannot answer.

Demo

https://ultra-bridge-xm71.vercel.app/

The page has example questions you can press. Open "How this was found" under any answer to see the exact GROQ query the agent ran to get there — nothing is hidden between the question and the data.

Code

https://github.com/demirajvazi10-max/Ultra-Bridge

How I Used Sanity

Schema. Seven document types: screenReader, source, action, command, concept, difference and guide. The dataset currently has 229 documents: 60 actions, 127 commands, 13 concepts, 12 differences, 7 guides and 8 sources.

Trust as data, not as an afterthought. Every command has a verification field (tested-by-author, cross-checked, first-party, third-party, recalled) and references to source documents. The system prompt tells the agent to say the verification level out loud whenever it uses a command, and to point to input help (Insert+1 in JAWS, NVDA+1 in NVDA) whenever a command is not yet confirmed. When two sources disagree, the disagreement is written on the command instead of hidden. Right now 11 commands are tested-by-author, 58 cross-checked, 44 first-party and 14 third-party — zero are still sitting at the weakest "recalled" level, because I keep a running checklist of what still needs a hands-on pass on a real screen reader.

Sanity Context, two modes.

GROQ mode serves the structured dataset. The agent fetches /initial-context over HTTP, puts it in its system prompt, and uses groq_query and schema_explorer for anything that names a specific command, key or action.
Knowledge Base mode serves seven guides written in prose, reserved for open-ended questions like "what should I learn first" or "how are the two screen readers different overall," where a single structured query would not be the right shape of answer. The Knowledge Base is created and built from the CLI (sanity context create, imports create, build --watch).

The two initial_context tools have the same name, so the agent drops both and inlines their content directly into the system prompt instead. If the Knowledge Base endpoint is unavailable, the agent falls back to the structured dataset only rather than failing the whole request.

Engineering for free-tier reality. The public demo runs on free model tiers, which cap tokens per minute hard enough that a naive integration falls over under real traffic. So the agent only exposes the two tools it actually needs (groq_query, knowledge_base_read), compacts every tool result before it goes back to the model (stripping fields the model does not need and hard-capping length), and chains four model providers (Google, Groq, Cerebras, Anthropic) so a rate limit on one provider fails over to the next instead of failing the request. The public page also rate-limits per visitor.

What I learned.

One endpoint serves one source type, so the structured data and the Knowledge Base need separate access paths.
GROQ match is tokenised text matching, so I use equality (==) for keys that contain +, or the match would silently split "Insert+F7" into pieces.
The Sanity CLI covers almost everything I needed: project, schema deploy, dataset import, tokens and the Knowledge Base. That mattered because I work from the command line.
Because Sanity's API was not reachable from where I built the first version, I wrote a small local server that speaks the Context MCP tool names and evaluates real GROQ with groq-js. It let me test the agent, the prompt queries and the whole interface offline, and it ships in the repo so anyone can try the project without accounts.

Accessibility. I am blind and use JAWS day to day, and I tested this myself before anyone else touched it. The interface has a skip link, real headings for every question and answer, one polite live region that announces the full answer once when it is complete, a "read last answer again" button, and stable focus in the question box. An end-to-end test drives it in Chromium and runs axe-core in light and dark colour schemes, so accessibility is checked automatically, not just by hand.

Sanity Project Details

Project ID: u2f7mbu5
Dataset: production (public)

How to Integrate Sanity CMS with Next.js 16 App Router

Sun, 26 Jul 2026 11:37:52 +0000

Managing content as a developer used to mean one of two things: hardcoding everything into your codebase or wrestling with a clunky WordPress dashboard. Neither feels great when your client wants to update a blog post at 10pm on a Friday without touching a single line of code.

That's exactly where Sanity CMS shines. It's a headless CMS with a fully customizable studio, a powerful query language called GROQ, and first-class support for Next.js. And in 2026, with Next.js 16's App Router fully matured, the two work together beautifully.

In this guide, you'll set up Sanity CMS inside a Next.js 16 App Router project from scratch: creating a project, defining a schema, writing GROQ queries, typing everything with TypeScript, and rendering rich text content with live updates. By the end, you'll have a working blog listing page and a dynamic post page, both powered entirely by Sanity.

Why Sanity Over Other Headless CMS Options?

There are plenty of headless CMS choices out there — Contentful, Strapi, Payload — so why Sanity?

Sanity Studio runs inside your Next.js app at /studio, so there's no separate admin URL to manage.
GROQ (Graph-Relational Object Queries) is more flexible and readable than GraphQL for content queries.
Real-time collaboration — multiple editors can work on content simultaneously.
Free tier is genuinely generous for most personal projects and small clients.

What We're Building

An embedded Sanity Studio running at /studio inside your Next.js app
A post schema with title, slug, excerpt, cover image, and rich text body
GROQ queries to fetch all posts and a single post by slug
Fully typed Sanity responses with TypeScript
A blog listing page and a dynamic post page using generateStaticParams
Real-time content updates using Sanity Live

What Is Sanity, Exactly?

Sanity is a headless CMS — meaning the content editor (Studio) is completely decoupled from how your content gets displayed. You configure Studio with code, content gets stored remotely in what Sanity calls the Content Lake, and your Next.js app queries that content using GROQ (Sanity's own query language).

💡 Tip: Think of Sanity Studio as a "window" into your remote content. The Studio configuration lives in your repo, but the actual blog posts, images, and data live on Sanity's servers — not in your codebase.

Prerequisites

Before we start, make sure you have:

Node.js 20+ installed
A Next.js 16 project with the App Router (TypeScript + Tailwind)
A free account at sanity.io
Basic familiarity with Next.js file-based routing

Step 1: Create a Sanity Project

First, let's create a new Sanity project from the CLI. If you don't have the Sanity CLI installed yet, run:

npm install -g @sanity/cli

Then inside your Next.js project root, initialize Sanity:

npx sanity@latest init

The CLI will walk you through a series of prompts. Here's exactly what to choose:

✔ Create a new project or select an existing one → Create new project
✔ Project name → whatever you like (e.g. my-blog)
✔ Select organization or create new
✔ Use the default dataset configuration? → Yes
✔ Configure Sanity MCP and agent skills for these editors? → Claude Code, GitHub Copilot CLI, VS Code
✔ Would you like to add configuration files for a Sanity project in this Next.js folder? → Yes
✔ Do you want to use TypeScript? → Yes
✔ Would you like an embedded Sanity Studio? → Yes
✔ What route do you want to use for the Studio? → /studio
✔ Select project template to use → Clean project with no predefined schema types
✔ Would you like to add the project ID and dataset to your .env.local file? → Yes

⚠️ Common Mistake: Picking the "blog" template instead of "Clean project" gives you pre-built schema types (post, author, category). That's fine if you want a head start, but this guide builds the post schema manually so you understand exactly what each field does — so we go with the clean template.

Once it finishes, your project folder should look like this:

.
├── .env.local
├── sanity.cli.ts
├── sanity.config.ts
├── (...and all your Next.js files)
└── src
    ├── app
    │   └── studio
    │       └── [[...tool]]
    │           └── page.tsx
    └── sanity
        ├── lib
        │   ├── client.ts
        │   ├── image.ts
        │   └── live.ts
        ├── schemaTypes
        │   └── index.ts
        ├── env.ts
        └── schema.ts

What Just Got Created?

A few of these files matter more than others:

src/sanity/lib/client.ts — a configured Sanity Client instance used to query content
src/sanity/lib/live.ts — exports sanityFetch and SanityLive, which power real-time content updates
src/sanity/env.ts — reads your project ID and dataset from .env.local
sanity.config.ts — configures Studio itself: schema types, plugins, and the studio route
app/studio/[[...tool]]/page.tsx — the catch-all route that renders the entire Studio UI at /studio

Your .env.local should now contain:

NEXT_PUBLIC_SANITY_PROJECT_ID="your-project-id"
NEXT_PUBLIC_SANITY_DATASET="production"

These are prefixed with NEXT_PUBLIC_ because a project ID and dataset name aren't sensitive — they're needed by the browser to talk to Sanity's API directly when previewing content.

Step 2: Install next-sanity

The CLI usually installs this for you, but if it's missing, add it manually:

npm install next-sanity

next-sanity is a toolkit of utilities built specifically for Next.js — it wraps Sanity Client with conventions for data fetching, caching, and live content updates so you're not wiring all of that together yourself.

Step 3: Create a Post Schema

Schemas in Sanity define what content editors are allowed to create in Studio — think of them as the shape of your content, similar to a database model.

Create a new schema file:

// src/sanity/schemaTypes/post.ts
import { defineField, defineType } from "sanity";

export const postSchema = defineType({
  name: "post",
  title: "Blog Post",
  type: "document",
  fields: [
    defineField({
      name: "title",
      title: "Title",
      type: "string",
      validation: (Rule) => Rule.required(),
    }),
    defineField({
      name: "slug",
      title: "Slug",
      type: "slug",
      options: { source: "title" }, // auto-generates slug from title
      validation: (Rule) => Rule.required(),
    }),
    defineField({
      name: "excerpt",
      title: "Excerpt",
      type: "text",
      rows: 3,
    }),
    defineField({
      name: "coverImage",
      title: "Cover Image",
      type: "image",
      options: { hotspot: true }, // lets editors set a focal point
    }),
    defineField({
      name: "publishedAt",
      title: "Published At",
      type: "datetime",
    }),
    defineField({
      name: "body",
      title: "Body",
      type: "array",
      of: [{ type: "block" }, { type: "image" }], // rich text + inline images
    }),
  ],
  orderings: [
    {
      title: "Published Date, New",
      name: "publishedAtDesc",
      by: [{ field: "publishedAt", direction: "desc" }],
    },
  ],
});

A quick breakdown of what's happening:

defineType registers a new document type — editors will see "Blog Post" as a creatable content type in Studio
defineField describes each individual field and its validation rules
The slug field with options: { source: "title" } auto-generates a URL-friendly slug from the title as the editor types
body uses type: "array" with block and image — this is Sanity's Portable Text format, a structured way of representing rich text that isn't tied to HTML

💡 Tip: Rule.required() enforces validation inside Studio itself. Editors literally cannot publish a post without a title or slug — no backend validation needed.

Step 4: Register the Schema

Defining a schema isn't enough — Studio needs to know it exists. Register it in the schema index:

// src/sanity/schemaTypes/index.ts
import { type SchemaTypeDefinition } from "sanity";
import { postSchema } from "./post";

export const schema: { types: SchemaTypeDefinition[] } = {
  types: [postSchema],
};

⚠️ Common Mistake: Forgetting this step is the #1 reason a new schema "doesn't show up" in Studio. Defining the type isn't enough — it has to be added to this types array.

Now start your dev server and visit http://localhost:3000/studio. You should see "Blog Post" listed as a content type, ready to create your first post.

Step 5: Write GROQ Queries

GROQ (Graph-Relational Object Queries) is Sanity's query language, purpose-built for querying structured, nested JSON-like content.

💡 Tip: If you've used SQL or MongoDB queries before, GROQ will feel different at first, but it's actually closer to JavaScript object/array syntax than SQL.

Create a queries file:

// src/sanity/queries.ts
import { groq } from "next-sanity";

// Fetch all posts for the blog listing page
export const allPostsQuery = groq`
  *[_type == "post"] | order(publishedAt desc) {
    _id,
    title,
    slug,
    excerpt,
    publishedAt,
    coverImage {
      asset-> { _id, url }
    }
  }
`;

// Fetch a single post by slug
export const postBySlugQuery = groq`
  *[_type == "post" && slug.current == $slug][0] {
    _id,
    title,
    slug,
    excerpt,
    publishedAt,
    coverImage {
      asset-> { _id, url }
    },
    body
  }
`;

// Fetch all slugs for generateStaticParams
export const allPostSlugsQuery = groq`
  *[_type == "post"] { "slug": slug.current }
`;

Here's what each part of the first query means:

*[_type == "post"] — selects every document where the type equals "post"
| order(publishedAt desc) — sorts results by publish date, newest first
{ ... } — a projection, meaning "only return these fields," similar to selecting specific columns in SQL
coverImage { asset-> { _id, url } } — the -> is a dereference, following the image asset reference to pull its actual URL

The second query uses $slug as a parameter and [0] to grab just the first matching result, since slugs are unique.

Step 6: Add TypeScript Types

Since GROQ queries return plain JSON, TypeScript has no way to infer their shape automatically. Define the types yourself so the rest of your app stays type-safe:

// src/sanity/types.ts
export interface SanitySlug {
  current: string;
}

export interface SanityImageAsset {
  _id: string;
  url: string;
}

export interface SanityImage {
  asset: SanityImageAsset;
}

export interface Post {
  _id: string;
  title: string;
  slug: SanitySlug;
  excerpt?: string;
  publishedAt: string;
  coverImage?: SanityImage;
  body?: unknown[]; // Portable Text blocks
}

💡 Tip: Sanity also offers a code generation tool (sanity typegen) that can generate these types automatically from your schema and queries. Writing them by hand works fine for smaller schemas, but it's worth exploring once your content model grows.

Step 7: Build the Blog Listing Page

With queries and types ready, fetching content becomes straightforward:

// app/blog/page.tsx
import { sanityFetch } from "@/sanity/lib/live";
import { allPostsQuery } from "@/sanity/queries";
import { Post } from "@/sanity/types";
import Link from "next/link";

export default async function BlogPage() {
  const { data: posts } = await sanityFetch({ query: allPostsQuery });

  return (
    <main className="max-w-3xl mx-auto px-4 py-12">
      <h1 className="text-4xl font-bold mb-8">Blog</h1>
      <ul className="space-y-8">
        {(posts as Post[]).map((post) => (
          <li key={post._id} className="border-b pb-8">
            <Link href={`/blog/${post.slug.current}`}>
              <h2 className="text-2xl font-semibold hover:underline">
                {post.title}
              </h2>
            </Link>
            {post.excerpt && (
              <p className="mt-2 text-gray-600">{post.excerpt}</p>
            )}
            {post.publishedAt && (
              <time className="text-sm text-gray-400">
                {new Date(post.publishedAt).toLocaleDateString("en-US", {
                  year: "numeric",
                  month: "long",
                  day: "numeric",
                })}
              </time>
            )}
          </li>
        ))}
      </ul>
    </main>
  );
}

Notice we're using sanityFetch from @/sanity/lib/live instead of calling the Sanity client directly. That's intentional — sanityFetch is a wrapper that ties into Next.js's caching and revalidation system, and it's also what enables the live-update behavior in the next step.

Step 8: Enable Sanity Live in the Root Layout

SanityLive is a component that subscribes to Sanity's Live Content API, so changes you publish in Studio show up on your site without a manual rebuild or redeploy.

// app/layout.tsx
import { SanityLive } from "@/sanity/lib/live";

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html
      lang="en"
      className={`${geistSans.variable} ${geistMono.variable} h-full antialiased`}
    >
      <body className="min-h-full flex flex-col">
        {children}
        <SanityLive />
      </body>
    </html>
  );
}

SanityLive doesn't render any visible UI — it just sits in the background and triggers revalidation whenever content changes in the Content Lake.

⚠️ Common Mistake: Placing SanityLive only on specific pages instead of the root layout. Since it needs to listen for changes globally, the root layout is the correct place for it.

Step 9: Style Rich Text with Tailwind Typography

Portable Text renders as plain HTML elements with no default styling, so headings, paragraphs, and lists will look unstyled out of the box. The Tailwind Typography plugin fixes this in one line.

Install it:

npm install @tailwindcss/typography

Add the plugin to your global CSS:

/* app/globals.css */
@import "tailwindcss";

@plugin "@tailwindcss/typography";

You'll use the prose class on any container wrapping Portable Text content in the next step.

Step 10: Build the Dynamic Post Page

This is where everything comes together — fetching a single post by slug, pre-rendering it at build time, and rendering its rich text body with PortableText.

// app/blog/[slug]/page.tsx
import { sanityFetch } from "@/sanity/lib/live";
import { allPostSlugsQuery, postBySlugQuery } from "@/sanity/queries";
import { Post } from "@/sanity/types";
import { PortableText } from "next-sanity";
import Image from "next/image";
import { notFound } from "next/navigation";

// Tell Next.js which slugs to pre-render at build time
export async function generateStaticParams() {
  const { data: slugs } = await sanityFetch({ query: allPostSlugsQuery });
  return (slugs as { slug: string }[]).map(({ slug }) => ({ slug }));
}

interface PageProps {
  params: Promise<{ slug: string }>;
}

export default async function PostPage({ params }: PageProps) {
  const { slug } = await params;
  const { data } = await sanityFetch({ query: postBySlugQuery, params: { slug } });

  if (!data) notFound(); // renders your app/not-found.tsx

  const post = data as Post;

  return (
    <article className="max-w-3xl mx-auto px-4 py-12">
      <h1 className="text-4xl font-bold mb-4">{post.title}</h1>

      {post.publishedAt && (
        <time className="text-sm text-gray-400 block mb-8">
          {new Date(post.publishedAt).toLocaleDateString("en-US", {
            year: "numeric",
            month: "long",
            day: "numeric",
          })}
        </time>
      )}

      {post.coverImage?.asset?.url && (
        <div className="relative mb-8 rounded-xl overflow-hidden">
          <Image
            src={post.coverImage.asset.url}
            alt={post.title}
            className="rounded-xl"
            priority
            width={1200}
            height={630}
          />
        </div>
      )}

      {Array.isArray(post.body) && (
        <div className="prose prose-lg max-w-none">
          <PortableText value={post.body} />
        </div>
      )}
    </article>
  );
}

A couple of things worth calling out:

generateStaticParams runs at build time and tells Next.js exactly which /blog/[slug] pages to statically generate, rather than rendering every post on demand
params is passed as a Promise — this matches Next.js 16's async params convention, which is why postBySlugQuery accepts it directly inside sanityFetch
notFound() triggers your custom not-found.tsx page if no post matches the slug, instead of crashing with an unhandled error

⚠️ Common Mistake: Forgetting Array.isArray(post.body) before rendering PortableText. If body is ever undefined (e.g. an editor saved a post without adding body content), PortableText will throw instead of failing gracefully.

Frequently Asked Questions

Why GROQ instead of a REST or GraphQL API?

GROQ is built specifically for querying deeply nested, structured content in a single request — including resolving references like images — without the boilerplate of a separate GraphQL schema or multiple REST calls.

Do I need to deploy Sanity Studio separately?

No. Since Studio is embedded inside your Next.js app at /studio, it deploys automatically whenever your Next.js app deploys — no separate hosting or build step required.

How do I render images from Sanity with Next.js Image optimization?

Use @sanity/image-url to build the image URL, then pass it to Next.js <Image>. Add cdn.sanity.io to the images.remotePatterns array in next.config.ts so Next.js is allowed to optimize it:

// next.config.ts
images: {
  remotePatterns: [{ protocol: "https", hostname: "cdn.sanity.io" }],
}

Is SanityLive safe to use in production?

Yes. It's designed for production use and is the recommended way to get real-time content updates without manually managing webhooks or polling.

Is the Sanity Studio accessible to the public?

By default, yes — anyone who visits /studio can see it (though they can't edit without a Sanity account with the right permissions). To fully restrict it, wrap the studio route in a middleware auth check or only run it in dev using an environment variable guard.

How is this different from my current MDX-based blog?

With MDX, content lives as files in your repo — every edit means a commit and redeploy. With Sanity, content lives in the cloud and can be edited through a UI, published instantly, and even handed off to non-technical writers without giving them repo access.

Can I add more content types later, like authors or categories?

Yes. Create a new schema file the same way you created post.ts, then register it in the types array inside schemaTypes/index.ts. Studio will pick it up immediately.

Conclusion

You now have a fully working Sanity CMS integration inside a Next.js 16 application — complete with an embedded Studio, a typed content model, GROQ-powered queries, and live content updates. From here, you can expand your schema with authors, categories, or custom block content, add Visual Editing for inline previews, or wire up on-demand revalidation through Sanity's webhooks.

This setup scales well beyond a simple blog — the same pattern works for landing pages, product catalogs, or any structured content your app needs to manage outside the codebase.

Useful Resources

Continue Learning

If you'd like to keep building on this foundation, check out these related guides:

📦 Source Code: View on GitHub