DEV Community: Aejkatappaja

My CI was green. At 150 connections, Postgres said no.

Aejkatappaja — Wed, 08 Jul 2026 08:58:08 +0000

I built a small training log in Go called go-gym. Two front doors over one backend: a JSON API and a server-rendered HTMX UI. Nothing exotic. It had been sitting there with a green CI for weeks: build passes, tests pass, lint passes.

Last week I added a /metrics endpoint, got curious about the numbers behind it, and pointed a load generator at the dashboard to see the p95.

It didn't get slow. It fell over.

The setup was hey, 150 concurrent connections, 15 seconds, against GET /app. The dashboard is the heaviest read in the app: a stats aggregate, a page of workouts, and the activity heatmap counts. I expected mediocre latency. Instead the worst request took 13.5 seconds and a big chunk of them came back as errors.

The server log said why:

FATAL: sorry, too many clients already (SQLSTATE 53300)

Postgres was refusing connections. 321 of them across the run.

The part I'd never thought about was the database setup, which was one line:

db, err := sql.Open("pgx", dsn)

database/sql hands you a connection pool for free, and I'd been quietly assuming it was sensible out of the box. It isn't. SetMaxOpenConns defaults to zero, and zero means unlimited. So under load, every query that can't grab an idle connection just opens a new one. At 150 concurrent requests each running a few queries, the pool opened connection after connection until it walked straight into Postgres's max_connections, which is 100 by default. Past that, Postgres says no, and the handler returns a 500.

The /metrics endpoint I'd added the day before turned out to be useful, not as the thing under test but as the instrument. I could watch the latencies climb while the error rate went up. The bottleneck wasn't the query. It wasn't a missing index, which is what I'd have guessed if you woke me up and asked. It was that I was opening hundreds of connections to a server that wanted a hundred.

The fix is four lines:

db.SetMaxOpenConns(25)
db.SetMaxIdleConns(25)
db.SetConnMaxIdleTime(5 * time.Minute)
db.SetConnMaxLifetime(time.Hour)

25 sits well under Postgres's 100, with room to spare for migrations, a background job, and anything else holding a connection. The first line is the one that matters. Once the pool is capped, extra requests don't open new connections. They wait for one to free up. The queue moves to the client side, where waiting is cheap, instead of the database side, where it's fatal.

You might be reaching for the reply: just use pgxpool. Fair. Its native pool defaults to a bounded size, so it wouldn't have blown up this way out of the box. But the store and the migrations (goose) are both built on database/sql, so switching isn't free, and you'd still have to size the pool for your database either way. The point isn't which pool you pick. It's that you have to know its default and set the bound. database/sql just happens to ship the dangerous default.

Same load test after the change:

`GET /app`, c=150, 15s	before	after
failed requests	321	0
p95 latency	requests were erroring out	32 ms
p99 latency		92 ms
throughput		~8,400 req/s

Before the fix, the worst request sat at 13.5 seconds before it gave up. After, the slowest 1% came back inside 92 milliseconds and nothing failed. One run, same machine, same dataset, so it's a clean comparison of the one thing I changed.

Let me be honest about what this is. It's hey on my laptop against a local Postgres with a small dataset, so the absolute numbers don't mean much. What's real is the failure mode. An unbounded pool will exhaust any connection-limited database the moment your concurrency is higher than the number of slots the database has, and it picks the worst possible time to do it, which is when you have traffic.

Two things stuck with me.

go build and my CI were green the entire time. Compiling tells you the types line up. It tells you nothing about what happens at 150 connections. The only reason I found this is that I ran the thing under load, which I did almost by accident.

And I would have guessed wrong. My reflex for "slow under load" is "add an index" or "there's an N+1 in there somewhere." The queries were fine. The pool was the problem, and I only knew that because the error said so, in plain words, in the log line up above. Measure the actual thing. Your instinct is a hypothesis, not an answer.

The four lines live in database.go, and there's a scripts/loadtest.sh in the repo if you want to reproduce the run. The whole project is at github.com/Aejkatappaja/go-gym. Set your pool limits. The default is a trap, and it stays quiet right up until it isn't.

Your design system's Shadow DOM breaks skeleton loaders. Here's the fix

Aejkatappaja — Tue, 07 Jul 2026 09:55:02 +0000

If you build with a Web Component design system (Stencil, Lit, FAST, or anything built on them like Ionic and Shoelace), skeleton loaders have a quiet failure mode: the content you want to measure isn't in the light DOM. It's inside a shadow root.

Say a row in your list is <user-card>. From the outside, that element looks nearly empty: the avatar, name, and bio live inside its shadow root, projected through slots. A skeleton tool that measures the light DOM walks in, finds no leaf elements to trace, and gives you a blank or collapsed placeholder. The skeleton doesn't match because the tool literally can't see the real layout.

Why it's hard?

Shadow DOM is an encapsulation boundary on purpose. querySelectorAll from the document doesn't cross it. getComputedStyle stops at the host. And slotted content is even trickier: a <slot> renders light-DOM children at a position defined inside the shadow tree, so where a node is in the DOM and where it paints are different places.

To generate an accurate skeleton for these components you have to:

Detect that a slotted element has an open shadow root
Walk into that root instead of stopping at the host
Resolve <slot> elements to the nodes actually projected into them
Measure the real painted leaves, wherever they live

The fix

phantom-ui does this behind one attribute, pierce-shadow:

  <phantom-ui loading pierce-shadow>
    <user-card></user-card>
    <user-card></user-card>
    <user-card></user-card>
  </phantom-ui>

With pierce-shadow on, it descends into each open shadow root follows the slots to their projected content, and measures the actual leaf elements inside.
The shimmer blocks land on the real avatar, the real heading, the real text lines, even though all of it is encapsulated.
Same structure-aware skeletons you'd get for plain markup, now for your component library.

One honest limit: this works on open shadow roots only. A closed shadow root is invisible to everything outside it by design, including this, so there's nothing to measure. Open roots are the common default, so most design systems are covered.

It composes with the rest of the library, so the same component also does the refresh/overlay mode and works across React, Vue, Svelte, Angular, Solid, Qwik and vanilla.
If you want the how-it-works on the core DOM-measurement technique, that's in the original write-up.

Try it

npm install @aejkatappaja/phantom-ui

Or via CDN:

<script src="https://unpkg.com/@aejkatappaja/phantom-ui/dist/phantom-ui.cdn.js"></script>

Links:

If your rows are custom elements and your skeletons never looked right, flip pierce-shadow on.

End-to-end type safety between Go and TypeScript

Aejkatappaja — Mon, 29 Jun 2026 12:45:20 +0000

You change a field on a Go struct. Three days later a TypeScript component reads that field, still expecting the old shape, and the bug ships. The compiler on each side was happy. The two compilers just never talked to each other.

This is the gap every Go plus TypeScript codebase has to close somehow. There are five common ways to close it. This post builds the same small app five times, one per approach, and compares what each one actually buys you. Every code sample comes from a companion repo where all five run.

What "type-safe" has to mean

"Generate types from the backend" is the easy 80 percent. The interesting part is the 20 percent where the two type systems disagree about what a value even is. So the demo app, a task tracker, is built around the cases that break pipelines:

A closed enum, TaskStatus, whose wire zero value is not a valid state.
A nullable field, assignee, sitting next to an optional field, dueDate. One can be present and null, the other can be absent. Most pipelines collapse the two.
An identifier that is a string on the wire but must not be mixed up with any other string in the program.
Cursor pagination, where "no more pages" is a different value from "empty page".
A typed not-found error, so the client branches on a known error and not on an HTTP status code it pattern-matched by hand.

Any approach can serialize a struct. The question is what happens to these five cases when they cross the language boundary.

The reframe: transport types are not domain types

Here is the idea the rest of the post hangs on, and the one most comparisons skip.

Code generators give you transport types. A generated ID is a plain string. A generated enum carries a zero value that means nothing. A generated optional field cannot tell you whether the value was null or simply absent. That is correct for a transport: it describes bytes on the wire. It is not what you want to write business logic against.

What you want is domain types. An ID that the compiler refuses to confuse with a different ID. An enum with no invalid member. A value that has already been parsed and can be trusted without re-checking.

So in the repo the domain lives in exactly one place, with no transport in it at all, and each approach maps its generated types onto that domain through a thin adapter. The cost and shape of that adapter, per approach, is the actual comparison.

The shared Go domain

Go has nominal typing already, so branded identifiers are just distinct types with a single sanctioned constructor.

type (
 UserID    string
 ProjectID string
 TaskID    string
)

// ParseUserID is the only way in. A raw string will not compile where UserID is
// expected, and a malformed one never becomes a UserID at all.
func ParseUserID(raw string) (UserID, error) {
 s, err := parseID("user id", raw)
 return UserID(s), err
}

The enum makes its unknown value explicit instead of leaning on the Go zero value.

type TaskStatus int

const (
 StatusUnknown TaskStatus = iota // zero value is not a real state, on purpose
 StatusTodo
 StatusInProgress
 StatusDone
)

func ParseTaskStatus(raw string) (TaskStatus, error) {
 if s, ok := wireToStatus[raw]; ok {
  return s, nil
 }
 return StatusUnknown, fmt.Errorf("task status: unknown %q", raw)
}

That StatusUnknown at position zero is the whole game. If todo were the zero value, any field that was never set would read as todo, and nothing would tell you. The nullable versus optional distinction is carried by pointers, where a nil *UserID is "no assignee" and a nil *time.Time is "no due date set".

The shared TypeScript domain

On the TypeScript side the same domain is expressed with zod, and the schema is the parser. This is parse don't validate: you parse untrusted input into a precise type once, at the edge, and downstream code receives the narrow type and never re-checks it.

const idPattern = /^[a-z]{2,5}_[0-9A-HJKMNP-TV-Z]{26}$/;

export const UserId = z.string().regex(idPattern).brand<"UserId">();
export type UserId = z.infer<typeof UserId>;

export const Task = z.object({
  id: TaskId,
  projectId: ProjectId,
  title: z.string().min(1),
  status: TaskStatus, // z.enum(["todo", "in_progress", "done"])
  assignee: UserId.nullable(), // present, value may be null
  dueDate: z.iso.datetime().optional(), // key may be absent entirely
});
export type Task = z.infer<typeof Task>;

.brand<"UserId">() is the TypeScript equivalent of Go's distinct type. At runtime it is still a string. At compile time, a plain string no longer fits where a UserId is wanted, so you cannot pass a project id to a function expecting a user id.
With exactOptionalPropertyTypes on, nullable() and optional() are genuinely different types, and the schema keeps them apart instead of melting both into undefined.

The page envelope carries the fifth case, cursor pagination, and it is the same shape everywhere:

export const TaskPage = z.object({
  items: z.array(Task),
  nextCursor: z.string().nullable(), // null means there is no next page
});

The typing point is the null. A nextCursor of null is "there are no more pages", which is a different state from an empty items array, and different again from the cursor being absent on the request. If nextCursor were typed as a plain string, the end-of-list case would be an empty string the client has to remember
to test for, which is exactly the kind of in-band signal that leaks. Each approach has to preserve that nullable on the way across: Connect uses an optional proto field the adapter maps to null, the OpenAPI document marks it nullable, GraphQL makes it a nullable String. The store returns a *string cursor for the same
reason, so "no more pages" is a nil pointer rather than a sentinel value.

Branding and runtime validation are two different decisions

It is worth separating two things the rest of this post keeps distinct, because conflating them leads to bad conclusions later.

A brand is a compile-time idea. A runtime check is a runtime cost. There is one way to attach a brand with zero runtime cost, and that is a cast:

const id = pt.id as UserId; // do not do this

This post never does that, and you should not either. A cast is an unchecked assertion. It tells the compiler "trust me" about a value that came off a wire, which is exactly the drift the brand was supposed to prevent. The brand now lies: the type says UserId, the value was never checked to be one.

So the only honest way to obtain a branded value is to parse it through the schema, which validates and brands in the same step:

const id = parseUserId(pt.id); // validates the format, returns a UserId, or throws

That means runtime validation is not redundant overhead bolted onto branding. It is the price of earning the brand without cheating.

Do you own both ends?

Before any tool, there is one architectural decision that changes the whole answer:
do you trust the producer? If the same team ships the Go server and the TS client, deploys them together, and the contract is generated from one source, then the wire is effectively trusted and the generated types already guarantee the structure.
Re-parsing every response with a second schema is mostly belt and suspenders, and the interesting move is to keep the validation in the source of truth (proto with protovalidate, a struct tag, a schema constraint) rather than hand maintaining a second one. If the producer is outside your control, a public API, a third party,
an older deployed version, then the wire is untrusted, the generated type is just a claim, and parsing at the edge earns its keep. The same five approaches below sit differently depending on which world you are in, so decide this first. The brand is not the question; the trust is.

Keep these two files in mind. Every approach below is judged on how much work it takes to get from its generated output back to these types.

Approach 1: ConnectRPC

A .proto file is the source of truth. buf generate produces a Go server stub and TypeScript message types from it, so the contract cannot drift between the two languages.

The proto bakes in two of our hard cases on purpose:

enum TaskStatus {
  TASK_STATUS_UNSPECIFIED = 0; // the proto analogue of StatusUnknown
  TASK_STATUS_TODO = 1;
  TASK_STATUS_IN_PROGRESS = 2;
  TASK_STATUS_DONE = 3;
}

message Task {
  string id = 1;
  string project_id = 2;
  string title = 3;
  TaskStatus status = 4;
  optional string assignee = 5;                 // null in the domain
  optional google.protobuf.Timestamp due_date = 6; // absent in the domain
}

Notice that proto3 has one presence mechanism, so assignee and due_date are both optional. The wire format cannot tell null from absent. That limitation becomes the adapter's job on both ends.

On the server, the generated handler interface is satisfied by a struct, and a compile-time assertion guarantees it. Rename an rpc and the build breaks before anything ships:

var _ tasktrackerv1connect.TaskTrackerServiceHandler = (*service)(nil)

Every request field is parsed into the domain before the store sees it, and the domain not-found error is mapped to a Connect code:

func (s *service) GetTask(ctx context.Context, req *connect.Request[tasktrackerv1.GetTaskRequest]) (*connect.Response[tasktrackerv1.GetTaskResponse], error) {
 id, err := domain.ParseTaskID(req.Msg.GetId())
 if err != nil {
  return nil, invalidArg(err) // CodeInvalidArgument
 }
 t, err := s.store.GetTask(ctx, id)
 if err != nil {
  return nil, toConnectError(err) // ErrNotFound -> CodeNotFound
 }
 return connect.NewResponse(&tasktrackerv1.GetTaskResponse{Task: toProtoTask(t)}), nil
}

The generated TypeScript types show the limitation directly. The proto compiler emits assignee?: string and dueDate?: Timestamp, both optional, because that is all proto presence can say. The client adapter reconstructs the domain distinction and validates the result through the branded schema:

export function toDomainTask(pt: ProtoTask): Task {
  const base = {
    id: pt.id,
    projectId: pt.projectId,
    title: pt.title,
    status: wireStatus(pt.status), // throws on UNSPECIFIED
    assignee: pt.assignee ?? null, // absent becomes null
  };
  const payload =
    pt.dueDate !== undefined
      ? { ...base, dueDate: timestampDate(pt.dueDate).toISOString() }
      : base; // absent stays absent
  return DomainTask.parse(payload); // untrusted wire -> branded domain
}

And the Connect error code is translated back into the same domain error the server raised, so the caller writes catch (e) { if (isNotFound(e)) ... } and never touches a status code:

function notFoundOr(kind: string, id: string, err: unknown): never {
  if (err instanceof ConnectError && err.code === Code.NotFound) {
    throw new NotFoundError(kind, id);
  }
  throw err;
}

The DomainTask.parse call above is the hand-written zod option, and it makes sense here only if you treat the server as untrusted. When you own both ends and deploy them together, proto already guarantees the structure, so re-parsing the whole payload with a second schema you maintain by hand is mostly wasted work. But recall the earlier point: you still cannot brand with a cast. So what carries the brand if not a hand-written schema?

The schema-driven answer is protovalidate. You put the constraints in the proto, next to the field they describe, and generate validators for both languages from that single source:

string id = 1 [(buf.validate.field).string.pattern = "^[a-z]{2,5}_[0-9A-HJKMNP-TV-Z]{26}$"];

protovalidate-go enforces it server side and protovalidate-es enforces it in the browser, both from the same rule. The constraint lives in the source of truth rather than in a zod file that can drift from the proto. This is the cleaner way to satisfy parse don't validate in the Connect world: validate from the schema, then brand the validated value, and keep the hand-written zod for the cases where the producer is genuinely outside your control.

What Connect gets right: one contract for two languages, generated service interfaces with compile-time enforcement, first-class typed errors through status codes, schema-driven runtime validation through protovalidate, and streaming when you need it. What it costs: a proto toolchain (buf), a build step, and an adapter layer to turn transport types into domain types, because the generated IDs are plain strings and the generated enum has that unspecified zero value. For greenfield RPC between a Go service and a TS client, this is the strongest default.

Approach 2: OpenAPI, spec first

Here an OpenAPI document is the source of truth, written by hand or assembled from components, and both sides generate from it: oapi-codegen for the Go server, openapi-typescript plus openapi-fetch for the TS client.

The defining trait is that the spec is a real artifact you own and review, not a byproduct of code. You can express nullable and required precisely, which maps better onto our null versus absent case than proto does:

Task:
  type: object
  required: [id, projectId, title, status, assignee]
  properties:
    assignee:
      type: string
      nullable: true # present, may be null
    dueDate:
      type: string
      format: date-time # not in `required`, so may be absent

openapi-typescript turns that into assignee: string | null and dueDate?: string, so the distinction survives generation, which is one fewer thing the adapter has to rebuild than in the proto case. The enum still generates as a bare string union and the IDs still generate as string, so the branded domain layer is the same idea: parse the generated response through the zod schemas at the boundary.

One version gotcha worth knowing in 2026: oapi-codegen does not yet support the OpenAPI 3.1 nullable union (type: [string, "null"]), so the document above is pinned to 3.0.3 and uses nullable: true. openapi-typescript handles 3.1 fine, so the limitation is on the Go side, and the snippet above is exactly what the companion repo ships.

What it gets right: the spec is the contract, it is readable, and it doubles as documentation and as the thing your public API consumers generate their own clients from. What it costs: writing and maintaining the document, and trusting that the server actually conforms to it, which oapi-codegen helps with by generating a strict server interface from the same spec, so a handler that returns the wrong shape fails to compile. Best fit when the API is REST shaped or public.

Approach 3: OpenAPI, code first

Same destination, opposite direction. The Go code is the source of truth and the OpenAPI document is derived from it, then the TypeScript side generates from that document exactly as before. There are two generations of tooling here, and they are not close in quality, so it is worth treating them separately.

The old way is comment driven. A tool like swaggo reads annotations above the handler and assembles a spec from them:

// @Summary Get a task
// @Param   id  path     string true "Task ID"
// @Success 200 {object} TaskResponse
// @Failure 404 {object} ErrorResponse
// @Router  /tasks/{id} [get]
func (h *Handler) GetTask(c echo.Context) error { ... }

This is the version that earns code first its bad reputation. The spec is only as precise as the comments, the type information survives a round trip through free text, and nullable versus optional comes down to annotation discipline rather than anything the compiler checks. The comments drift from the types they describe and nothing fails when they do. In fairness, a team that fails CI when the regenerated spec no longer matches the handlers can keep this honest, and some run it that way for years. But then it is the pipeline holding the contract, not the compiler, which is the same fragility the manual approach has.

The modern way, in 2026, does not use comments at all. Libraries like Huma and Fuego derive the OpenAPI document from real Go structs and generics, so the input and output types of a handler are the spec:

type idInput struct {
 ID string `path:"id"`
}

// Assignee is a pointer with no omitempty, so Huma marks it required and nullable.
// DueDate uses omitempty, so Huma marks it optional. The struct is the schema.
type taskBody struct {
 ID        string     `json:"id"`
 ProjectID string     `json:"projectId"`
 Title     string     `json:"title"`
 Status    string     `json:"status" enum:"todo,in_progress,done"`
 Assignee  *string    `json:"assignee"`
 DueDate   *time.Time `json:"dueDate,omitempty"`
}

type taskOutput struct {
 Body taskBody
}

huma.Register(api, huma.Operation{
 OperationID: "getTask",
 Method:      http.MethodGet,
 Path:        "/tasks/{id}",
}, s.getTask) // func(ctx, *idInput) (*taskOutput, error), parses the id into the domain

The spec cannot lag the implementation, because there is no separate document and no comment layer: the spec is a projection of the Go type system. Request validation comes from struct tags and runs before the handler, and errors follow RFC 7807 by default (the handler returns huma.Error404NotFound for the domain not-found sentinel), which gives the TypeScript side a typed error shape to generate against. Nullable versus optional is now expressed in Go types and field tags rather than prose, so it is as precise as your structs are.

What it gets right, with Huma or Fuego: a single source of truth that is real Go code, a spec that is generated rather than written, runtime validation derived from the same types, and typed errors out of the box. What it costs: you are coupled to the framework's way of describing handlers, and you have less direct control over the emitted schema than when you author the document by hand. Pick the modern libraries over the comment based tools without hesitation. Code first stopped meaning magic comments a while ago.

Approach 4: GraphQL

A GraphQL schema is the source of truth. gqlgen generates Go resolvers from it, graphql-codegen generates TypeScript types and typed operations from it and from your queries.

GraphQL is the one approach with native support for branded types end to end, through custom scalars. You declare a scalar in the schema and map it to a branded type on each side, so the generated client already hands you a UserId rather than a string:

scalar UserId
scalar TaskId
scalar DateTime

type Task {
  id: TaskId!
  assignee: UserId # nullable by default
  dueDate: DateTime # nullable by default
  status: TaskStatus!
}

// graphql-codegen config
scalars: {
  UserId: "@gotstypes/domain#UserId",
  TaskId: "@gotstypes/domain#TaskId",
  DateTime: "string",
}

That is genuinely less adapter code than the RPC and REST approaches, because the nominal types come straight out of generation: getTask().id is typed as a TaskId. The honest caveat is that this branding is a compile-time assertion the codegen makes from the scalar config, not a runtime check, which is the same trust gap as a cast. So the companion repo still parses each response through the domain schema for runtime safety. The win is less boilerplate and branded types by default, not validation. It also rests on the scalars block staying in sync with the domain types: nothing stops that mapping from drifting, so the safety is only as good as the config is maintained.

The cost is the rest of GraphQL: nullability is per field and defaults to nullable, so you spend ! discipline everywhere; the runtime is heavier; and you take on resolver wiring, n plus one concerns, and a query language your frontend now has to learn. The null versus absent case bends too: GraphQL has only null in its output, no notion of absent, so the optional dueDate comes back as string | null and the client maps a null back to absent to line up with the domain. Worth it when the data is genuinely graph shaped and many clients want different slices of it.

Approach 5: manual types with a runtime parser

No code generation. The Go side writes its JSON DTOs by hand, and the TypeScript side reuses the shared zod schema as both the type and the validator, parsing every response at the boundary. This is the baseline the others are measured against.

const data = await fetch(`/tasks/${id}`).then((r) => r.json());
const task = Task.parse(data); // the shared domain schema: branded, validated, or it throws

What it gets right: zero toolchain, zero build step, full control, and .brand() gives you branded types natively with no adapter at all, because the schema is already the domain. Runtime validation is built in rather than bolted on. What it costs: the contract is a promise, not a guarantee. Nothing connects the Go struct to the zod schema, so the two drift the moment someone forgets. It works for a small surface or a spike, and stops scaling the day the API grows faster than your discipline.

The TypeScript-only tools: tRPC and Pothos

Two names come up constantly in this space, and both assume a TypeScript backend, so neither fits a Go one. They are worth a direct answer.

People search for "tRPC with Go" constantly, and the answer is you cannot. tRPC achieves its type safety by sharing the actual TypeScript types between client and server through a TypeScript import. There is no schema and no code generation,
which is exactly why it is frictionless, and exactly why it is TypeScript on both ends only. A Go backend has no TypeScript types to import. If you reached for this post hoping to wire tRPC to Go, the closest thing in spirit is ConnectRPC: schema first, generated clients, typed errors, and a similar end-to-end feel.

Pothos is the same story from the GraphQL side. It is a code-first GraphQL schema builder with excellent type inference, but it builds the schema in TypeScript, so it fills the role gqlgen fills in this post, just for a Node backend instead of a Go one. If your backend were TypeScript, Pothos would be a strong way to define the
schema, and the client would still generate from it with graphql-codegen exactly as shown above. With a Go backend the schema comes from gqlgen, and Pothos does not enter the picture.

Scorecard

Code first below means the modern struct based libraries (Huma, Fuego), not the
comment based tools.

	Connect	OpenAPI spec-first	OpenAPI code-first	GraphQL	Manual
Source of truth	proto	the document	Go structs	schema	nothing shared
Contract enforced	compile time	generation	Go type system	generation	by hand
Null vs absent	adapter rebuilds it	expressed in spec	Go types and tags	per field, subtle	you decide
Branded types	adapter layer	adapter layer	adapter layer	native scalars	native zod
Runtime validation	protovalidate or zod	spec then zod	struct tags, then zod	add zod at edge	built in
Typed errors	status codes	convention	RFC 7807 native	error extensions	by hand
Toolchain weight	buf, codegen	codegen	one library	two codegens, runtime	none
Maintenance at scale	proto evolves under buf breaking checks	the document can grow into a burden on large or public APIs	low, falls out of Go types	schema plus codegen config plus resolvers	discipline bound, drifts silently
Streaming	yes	no	no	subscriptions	no

A note on payload size

People ask about performance, so here is the one number that is honest to give.
The companion repo serializes the same task into each wire format and measures the bytes, raw and after gzip. This is serialization only, not latency or throughput, and in a real service the database and network dominate, not a few hundred bytes.

	single task (raw / gzip)	50 tasks (raw / gzip)
Protobuf (binary)	128 / 134 B	6550 / 193 B
Connect (proto JSON)	232 / 208 B	11710 / 286 B
OpenAPI / REST JSON	215 / 197 B	10829 / 281 B
GraphQL JSON	233 / 209 B	10848 / 296 B

Protobuf binary is about half the raw size, and the gap widens with list length.
After gzip it shrinks: for a single small object the formats land within tens of bytes of each other, and the binary can even be larger than its raw form because gzip has fixed overhead on tiny inputs. At list scale the binary stays around a third smaller gzipped, which matters if you ship large responses and is a rounding error if you do not. The three JSON formats are within a few percent of each other, because they are all just JSON with different envelopes. None of this is a reason to pick an approach. The source of truth is.

Verdict

There is no single winner, but the choice is not a coin flip either.

Reach for ConnectRPC for greenfield typed RPC between a Go service and a TS client. One contract, generated both sides, typed errors, streaming. The adapter to branded domain types is small and worth it.
Reach for OpenAPI spec first when the API is REST shaped or public, so external consumers can generate their own clients from a document you own.
Reach for GraphQL when the data is graph shaped and many clients want different slices. The custom scalar support for branded types is the best of the five, but you pay for it with the rest of GraphQL.
Reach for OpenAPI code first with Huma or Fuego when the Go service is the sole producer and you want the spec to fall out of real Go types rather than be maintained by hand. This is a genuinely strong default now, not the weak option it was in the comment driven era. Skip the comment based tools.
Reach for manual plus zod for a spike or a tiny surface, and plan to migrate before discipline becomes the only thing holding the contract together.

The thing none of them do for free is hand you domain types. They all hand you transport types. Branded ids, exhaustive enums, and the null versus absent distinction live in an adapter you write once and keep thin. Decide where your source of truth lives first. The rest is the cost of getting from there back to a type you can actually trust.

The runnable code for all five is in the companion repo, one directory each, sharing one domain.

I built phantom-ui - a Web Component that generates skeleton loaders from your real DOM

Aejkatappaja — Tue, 14 Apr 2026 12:01:19 +0000

Updated for v1.4.0: added a refresh / stale-while-revalidate overlay mode (jump).

Skeleton loaders are one of those things that sound simple until you actually build them. You end up hand-coding a second layout with gray blocks that kind of matches the real one. Then the design changes, nobody updates the skeleton, and it drifts out of sync. Classic.

The idea

The DOM already knows what your UI looks like. Positions, sizes, border-radius, everything. So why are we manually recreating that as a skeleton?

phantom-ui wraps your content with <phantom-ui loading>, walks the DOM tree, measures every leaf element with getBoundingClientRect, and overlays animated shimmer blocks at the exact same coordinates. When loading ends, it fades out.

<phantom-ui loading>
  <div class="card">
    <img src={user?.avatar} width="48" height="48" />
    <h3>{user?.name ?? "Placeholder Name"}</h3>
    <p>{user?.bio ?? "A short bio goes here."}</p>
  </div>
</phantom-ui>

No separate skeleton template. No config file. Your real component is the skeleton.

How it works under the hood

When the loading attribute is set, phantom-ui:

Hides the slotted text with -webkit-text-fill-color: transparent and images with opacity: 0
Walks the slotted DOM tree recursively
Skips containers and captures leaf elements. Certain tags (IMG, SVG, VIDEO, CANVAS, IFRAME, INPUT, TEXTAREA, BUTTON) are always treated as leaves regardless of children
Calls getBoundingClientRect on each to get position and size relative to the host
Reads border-radius from computed styles
For container elements with a visible background, border, or box-shadow, it captures those styles separately (using getComputedStyle with individual borderWidth/borderStyle/borderColor since the border shorthand returns empty in computed styles)
Renders absolutely-positioned shimmer blocks inside the Shadow DOM overlay

The shimmer animation is pure CSS, a linear-gradient sweep using background-position animation. No JavaScript animation loop.

.shimmer-block::after {
  background: linear-gradient(90deg, var(--bg) 30%, var(--color) 50%, var(--bg) 70%);
  background-size: 200% 100%;
  animation: shimmer-sweep 1.5s linear infinite;
}

A ResizeObserver watches for layout changes. A MutationObserver catches DOM mutations (it disconnects during measurement to avoid re-triggering itself when injecting measurement spans for table cells). Both re-trigger _measure() automatically so the skeleton stays in sync. Observers are only active while loading is true and are properly disconnected on cleanup.

Measurement is batched via requestAnimationFrame, so multiple DOM mutations in the same frame result in a single measurement pass instead of thrashing.

Table cell handling

Table cells (<td>, <th>) get special treatment. A <td> is often wider than its text content because of table layout. phantom-ui temporarily injects a <span> inside the cell, measures the span's width instead of the cell's, then removes it. This produces shimmer blocks that match the text width, not the full column width.

Dual Shadow DOM / Light DOM styles

Content hiding requires two separate style strategies. The shimmer overlay lives in Shadow DOM (scoped, encapsulated). But the slotted content lives in Light DOM, and Shadow DOM styles can't fully target deep descendants of slotted elements. So phantom-ui injects a small stylesheet into the document head that targets phantom-ui[loading] * to hide text and images. This is done once, deduplicated by checking for an existing style element ID.

The loading attribute uses a custom Lit converter that treats the string "false" as falsy:

converter: {
  fromAttribute: (value) => value !== null && value !== "false",
  toAttribute: (value) => (value ? "" : null),
}

This means <phantom-ui loading="false"> removes the skeleton, which avoids a common gotcha with frameworks that serialize booleans as strings.

"But you need the data to render the DOM?"

This is the first thing people ask. If the content is behind {#if data} or data && <Component />, there's nothing in the DOM to measure. Fair point.

The trick is to always render the structure with fallback values:

<phantom-ui loading={isLoading}>
  <div className="card">
    <img src={user?.avatar ?? ""} width="48" height="48" />
    <h3>{user?.name ?? "Placeholder Name"}</h3>
    <p>{user?.bio ?? "A short bio goes here."}</p>
  </div>
</phantom-ui>

The fallback text gives elements a size. It's invisible during loading anyway. Yeah, it's a tradeoff, you structure your template a bit differently. But you never maintain a separate skeleton.

For elements that don't have a natural size yet (image without width/height, a div filled by JS), you can force dimensions:

<img data-shimmer-width="200" data-shimmer-height="150" />

phantom-ui will use those values instead of the measured ones. This also works for elements with zero size, they won't be skipped if an override is present.

For lists where you don't know the count, the count attribute repeats skeleton rows from a single template:

<phantom-ui loading count="5" count-gap="12">
  <div class="user-row">
    <img width="32" height="32" />
    <span>Placeholder</span>
  </div>
</phantom-ui>

When using count, if the template element has a visible background, border, or box-shadow, phantom-ui replicates those on each repeated row as .shimmer-container-block elements. This means your skeleton rows look like real cards, not just floating shimmer blocks.

Why a Web Component?

I didn't want to build a React version, then a Vue version, then a Svelte one. One component that works everywhere, that's it.

phantom-ui is built with Lit (~8kb total) and registers as <phantom-ui>. Works out of the box with:

React 19+ sets properties natively on custom elements
Vue detects properties via the in operator
Svelte handles boolean attributes natively
Angular with CUSTOM_ELEMENTS_SCHEMA and [attr.loading]="loading() ? '' : null"
Solid with attr:loading={loading() ? "" : null} (the attr: prefix forces attribute mode, and null removes it, important because attr:loading={false} would set loading="false" in the DOM, which the CSS selector phantom-ui[loading] still matches)
Qwik with a dynamic import() in useVisibleTask$ and a ready signal guard
HTMX with a CDN script tag and hx-on::after-swap to remove the loading attribute
Vanilla HTML just a script tag

Zero-config TypeScript setup

There's no postinstall hook, nothing runs when you install the package. Setup is an optional one-time command you run when you want it:

npx @aejkatappaja/phantom-ui init

It detects your framework and:

Generates a phantom-ui.d.ts with JSX IntrinsicElements declarations tailored to your framework (React, Solid, Qwik each need different type augmentations)
For SSR frameworks (Next.js, Nuxt, SvelteKit, Remix, Qwik), adds the pre-hydration CSS import to your root layout

Both steps are tiny and documented for manual setup too. Your source is never touched unless you run the command.

The TypeScript types include full JSDoc on every property, so you get autocomplete and hover docs in your editor. The package also ships a Custom Elements Manifest (custom-elements.json) for IDE tooling.

Animation modes and shimmer direction

4 animation modes:

shimmer (default), a gradient sweep moving across each block
pulse, opacity oscillation between full and faded
breathe, subtle scale and opacity breathing effect
solid, static blocks with no animation

<phantom-ui loading animation="pulse">...</phantom-ui>

Shimmer direction controls the sweep direction of the gradient. Only applies to animation="shimmer":

ltr, left to right (default)
rtl, right to left, useful for RTL layouts (Arabic, Hebrew)
ttb, top to bottom
btt, bottom to top

<phantom-ui loading shimmer-direction="rtl">...</phantom-ui>

Under the hood, each direction changes the gradient angle (90deg vs 180deg) and the background-size/background-position axis. The CSS uses :host([shimmer-direction="rtl"]) selectors to swap the keyframes, no JS involved.

Stagger: delay in seconds between each block's animation start. Creates a wave effect where blocks animate one after another.

<phantom-ui loading stagger="0.05">...</phantom-ui>

Reveal: smooth fade-out transition in seconds when loading ends. The overlay gets an opacity: 0 transition via a .revealing class, then removes itself from the DOM after the transition completes.

<phantom-ui loading reveal="0.3">...</phantom-ui>

Refresh mode (overlay)

Skeletons are for the first load, when there's no data yet. But a lot of loading is really a refetch: you already have a result on screen and you're refreshing it. Hiding it behind a skeleton feels like a step backwards.

mode="overlay" handles that. Your existing content stays on screen, dimmed, while the same structure-aware light glint sweeps over it. It's not clickable during the refresh, so users can't act on stale data, but it stays readable and announced with aria-busy.

// skeleton on first load, overlay on refetch
<phantom-ui loading={isLoading || isFetching} mode={isLoading ? "skeleton" : "overlay"}>
  <div className="grid">{items.map(renderRow)}</div>
</phantom-ui>

Tune the dim with the --phantom-content-opacity CSS variable (default 0.5). It reuses the same measurement engine as the skeleton, so the glint follows your real layout.

Fine-grained control

data-shimmer-ignore keeps an element and its children visible during loading. Useful for static labels, navigation, or interactive elements that should remain usable:

<nav data-shimmer-ignore>
  <a href="/">Home</a>
</nav>

The light DOM CSS resets -webkit-text-fill-color, pointer-events, and opacity for ignored elements and their descendants.

data-shimmer-no-children captures a container as a single shimmer block instead of walking its children. Useful for charts, progress bars, or any element where child structure doesn't map to meaningful skeleton blocks:

<div class="chart" data-shimmer-no-children>
  <canvas></canvas>
</div>

data-shimmer-width / data-shimmer-height override measured dimensions. If only one axis is set and the other is zero, the element is still captured (normally zero-size elements are skipped):

<div data-shimmer-width="120" data-shimmer-height="24"></div>

Accessibility

phantom-ui automatically sets aria-busy="true" on the host element when loading, and aria-busy="false" when loading ends. Screen readers use this to announce that content is being loaded. The shimmer overlay also has aria-hidden="true" so assistive technology ignores the decorative blocks entirely.

While loading, the placeholder content underneath is also made inert, so it stays out of the tab order and the accessibility tree. Keyboard and screen reader users never land on the invisible elements while the skeleton is showing. Anything you mark with data-shimmer-ignore stays interactive.

SSR support

phantom-ui uses browser APIs (getBoundingClientRect, ResizeObserver, customElements), so the import must happen client-side. But the <phantom-ui> HTML tag is safe in server-rendered markup. The browser treats it as an unknown element until hydration.

The problem: before JavaScript loads, content inside <phantom-ui loading> can briefly flash as visible text. The package ships ssr.css that hides this content immediately with no JS:

@import "@aejkatappaja/phantom-ui/ssr.css";

The optional init command adds this import to your layout file, or you add the one line yourself.

Performance

Benchmarked on a Mac Studio M4 Max:

Elements	Measurement time
100	< 3ms
500	< 15ms
1000	< 31ms

The measurement runs once per loading toggle (plus re-runs on resize/mutation). It's a single synchronous DOM walk, no layout thrashing, since getBoundingClientRect reads are batched before any writes.

Try it

npm install @aejkatappaja/phantom-ui

Or via CDN:

<script src="https://unpkg.com/@aejkatappaja/phantom-ui/dist/phantom-ui.cdn.js"></script>

Links:

Feedback welcome, especially on edge cases you've hit with skeleton loaders.