Forem: Krzysztof Żuraw

CSS aspect ratio property

Krzysztof Żuraw — Sun, 15 Feb 2026 14:11:22 +0000

I recently learned that I can use CSS aspect ratio property to tell browser how tall should image be responsively:

img {
    width: '100%',
    aspect-ratio: "333 / 298" /* width / height of image */
}

Thanks to that browser will know how tall the image should be without hardcoding image height. It also prevents layout shift (CLS) because browser reserves the correct space before image loads.

Branded Types in TypeScript: techniques

Krzysztof Żuraw — Wed, 11 Jun 2025 05:58:04 +0000

In this post, I’ll walk you through several ways to implement branded types in TypeScript. If you’re new to the concept, check out this intro to branded types before diving in.

Branded types let you create more specific types from primitives like string or number. This helps TypeScript catch bugs where you might accidentally mix up values that are technically the same primitive type but represent different concepts (e.g., UserId vs. string).

1. Using a Type Wrapper

type UserId = string & { __brand: 'UserId' };

const createUserId = (raw: string): UserId => {
  // Add validation logic here if needed
  return raw as UserId;
};

const userId = createUserId("user_id_42");

function getUser(id: UserId) { /* ... */ }

getUser(userId);        // ✅ Works
getUser("user_id_42");  // ❌ Type error

This pattern is lightweight and doesn’t require any extra dependencies. You define a branded type and enforce its usage via a factory function (createUserId). This ensures only properly branded values are passed around your codebase.

Pros:

Zero dependencies
Simple to implement

Cons:

No runtime validation unless you add it yourself
The __brand property is only a TypeScript construct—it doesn’t exist at runtime

2. Using JavaScript Classes / Objects

class UserId {
  constructor(private _id: string) {}

  get id() {
    return this._id;
  }
}

const userId = new UserId("user_id_42");

function getUser(id: UserId) { /* ... */ }

getUser(userId);        // ✅ Works
getUser("user_id_42");  // ❌ Type error

If you want to encapsulate logic (like validation, formatting, or transformation), classes are a good fit. For simple cases, though, this approach can be a bit verbose.

Pros:

Can add methods, validation, and encapsulate logic
Runtime type information

Cons:

More boilerplate
Not always necessary for simple cases
Hard to compare classes - instead of comparing UserId you need to compare its internal id property

3. Using Zod’s `brand()` Method

import { z } from "zod";

const userIdSchema = z
  .string()
  .startsWith("user_id")
  .brand("UserId");

export const createUserId = (raw: string) => userIdSchema.parse(raw);

export type UserId = z.infer<typeof userIdSchema>;

function getUser(id: UserId) { /* ... */ }

const userId = createUserId("user_id_42");
getUser(userId);        // ✅ Works
getUser("user_id_42");  // ❌ Type error

If you’re already using Zod, its `.brand()` method gives you branded types with built-in validation. This is especially handy for APIs or form inputs.

Pros:

Built-in validation
Clean integration with Zod schemas
Type-safe and runtime-safe

Cons:

Requires Zod as a dependency

Summary

Type wrapper: Great for lightweight use cases, no dependencies.
Class-based: Useful when you need encapsulation or extra logic.
Zod brand: Perfect if you already use Zod and want validation + branding.

Branded types are a powerful way to make your TypeScript code safer and more expressive. Pick the approach that fits your project and team best! We in Saleor use both Zod brand and classes.

Dynamic Configuration for MCP Servers Using Environment Variables

Krzysztof Żuraw — Thu, 29 May 2025 06:24:56 +0000

This blog post explains how to configure Model Context Protocol (MCP) server that can be dynamically controlled through environment variables.

Problem

When setting up mcp-graphql, we needed a way for the MCP server to use a dynamic GraphQL endpoint and token. Hardcoding these values was not an option, as different Saleor environments require different configurations.

Solution

Here’s what we did:

Created a shell script to manage the mcp-graphql startup.
Loaded the endpoint and token from a .env file within the script.
Launched the MCP server using these environment variables.
Used this shell script as the entry point for MCP configuration in clients like Cursor or VSCode

Below is the shell script (start-mcp-graphql.sh) that performs steps 1–3:

#!/usr/bin/env bash

set -a
# Load environment variables from .env file next to this script
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/.env"
set +a

ENDPOINT="$MCP_GRAPHQL_ENDPOINT" HEADERS="{\"Authorization\":\"Bearer $MCP_GRAPHQL_TOKEN\"}" npx mcp-graphql

Using the Script in MCP Clients

To use this setup with Cursor, add the following to your configuration:

{
  "mcpServers": {
    "Saleor GraphQL API": {
      "command": "./mcp/start-mcp-graphql.sh"
    }
  }
}

For VSCode, configure the server as follows:

{
  "servers": {
    "Saleor GraphQL API": {
      "type": "stdio",
      "command": "${workspaceFolder}/mcp/start-mcp-graphql.sh"
    }
  }
}

Summary

With this approach, you can easily configure your MCP server dynamically using environment variables. You’ll find all the source code, scripts, and editor configs ready to explore in the Saleor apps repository.

Custom metrics using @vercel/otel

Krzysztof Żuraw — Sun, 06 Apr 2025 10:07:53 +0000

This guide explains how to properly implement custom metrics in Next.js applications using @vercel/otel. Before proceeding, you should be familiar with:

OpenTelemetry (OTEL) fundamentals
OTEL metrics
Basic usage of @vercel/otel in Next.js applications

Problem

When implementing custom metrics with @vercel/otel in Next.js Route Handlers, you might notice that metrics aren't being properly reported to your OTEL collector. This happens because Route Handlers complete their execution before the metrics have a chance to be flushed to the collector.

Solution

To ensure all metrics are properly collected, we need to:

Create a custom MetricProvider
Register it with OTEL
Manually flush metrics at the end of Route Handler execution

Here's the step-by-step implementation:

First, create a custom metric provider:

// meter-provider.ts
import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";

import { Resource } from "@opentelemetry/resources";
import { MeterProvider } from "@opentelemetry/sdk-metrics";
import { createMetricsReader } from "@saleor/apps-otel/src/metrics-reader-factory";

export const meterProvider = new MeterProvider({
  readers: [
    new PeriodicExportingMetricReader({
      exporter: new OTLPMetricExporter(),
    }),
  ],
  // Create new resource as `@vercel/otel` creates its own under the hood and doesn't expose it
  // https://github.com/vercel/otel/issues/153
  resource: new Resource(),
});

Next, set up the OTEL instrumentation:

// src/instrumentation.ts
import { metrics } from "@opentelemetry/api";
import { registerOTel } from "@vercel/otel";

export const register = () => {
  registerOTel();
  metrics.setGlobalMeterProvider(meterProvider);
};

Finally, implement the manual flush in your Route Handlers:

// app/api/route.ts
import { headers } from "next/headers";

import { meterProvider } from "./meter-provider"; // previously created file

export async function GET(request: Request) {
  after(async () => {
    await meterProvider.forceFlush();
  });

  return new Response("Hello from Route Handler", {
    status: 200,
  });
}

With this setup, your custom metrics will be properly flushed and collected before the Route Handler completes its execution. This ensures no data loss and accurate metric reporting in your observability pipeline.

DynamoDB access modeling for multi-tenant services

Krzysztof Żuraw — Fri, 14 Feb 2025 10:11:00 +0000

Recently at Saleor we encountered the challenge of implementing multi-tenancy in Saleor apps. In this blog post, I'll share my experience with access modelling when using DynamoDB for multi-tenant services.

Problem

When developing a Saleor app that can be installed for multiple tenants, we faced several requirements:

Ensure data isolation between tenants
Provide quick access times for serverless functions (which are main components of Saleor apps)
Achieve good scalability

Given these requirements, we chose DynamoDB as our database solution. Its flexible schema, low latency, and ability to scale horizontally made it an ideal fit for our multi-tenant Saleor app.

Modelling Approach

Before diving into implementation, it's crucial to model our data and access patterns. Let's take the example of storing app configurations for multiple tenants.

Access Patterns

We identified two main access patterns:

Read operations:
- API routes: Retrieve API keys for third-party services from saved configuration
- UI: Display current configuration values to end-users (via tRPC)
Write operations:
- UI: Update app configuration (via tRPC)

Data Structure

Our app configuration typically consists of:

Encrypted fields (e.g., API keys for third-party services)
Mappings between Saleor channels and app configuration

DynamoDB Table Design

Following recommendations from The DynamoDB Book we decided to store all data for each app in a single DynamoDB table. Here's how we structured our table:

Primary Key (PK)

We use a composite primary key in the format:

{saleorApiUrl}#{saleorAppId}

This structure ensures that:

Each tenant's data is isolated
New app installations don't access data from previous installations
App can fetch multiple entities from DynamoDB in one request

Sort Key (SK)

Our sort key follows the format:

APP_CONFIG#{configKey}

Where configKey represents the configuration version. This approach allows for easy future migrations to new configuration versions.

Benefits of This Design

Multi-tenancy: The saleorApiUrl in the PK enables multi-tenancy by separating data for different Saleor instances.
Versioning: The configKey in the SK allows for multiple versions of configurations.
Flexibility: We can easily add other entity types by using different SK prefixes (e.g., TRANSACTION#{transactionId} for storing webhook-related information).

Implementation Example

Here's a TypeScript example of how we might query our DynamoDB table:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, GetCommand } from "@aws-sdk/lib-dynamodb";

const client = new DynamoDBClient({});
const docClient = DynamoDBDocumentClient.from(client);

async function getAppConfig(saleorApiUrl: string, saleorAppId: string, configKey: string) {
  const command = new GetCommand({
    TableName: "AppTable",
    Key: {
      PK: `${saleorApiUrl}#${saleorAppId}`,
      SK: `APP_CONFIG#${configKey}`,
    },
  });

  const response = await docClient.send(command);
  return response.Item;
}

Summary

When modelling DynamoDB access for multi-tenant services:

Identify access patterns: Understand how your data will be read and written.
Define data structure: Determine what needs to be stored in DynamoDB.
Design table structure: Choose appropriate primary and sort keys to enable efficient querying and ensure data isolation between tenants.

By following these steps, we've created a scalable and efficient DynamoDB structure for our multi-tenant Saleor app. This approach allows us to maintain data isolation, achieve quick access times, and easily adapt to future requirements.

How to link a local npm dependency with pnpm

Krzysztof Żuraw — Sun, 13 Aug 2023 11:48:05 +0000

I have learned how to correctly link a local npm dependency when using pnpm. Here is the process:

Execute pnpm install ./your-library.tgz.
Include the following code in your package.json file:

{
  "pnpm": {
    "overrides": {
      "your-library": "file:./your-library.version.tgz"
    }
  }
}

Your dependency should now be properly linked!

How you properly test your React hook methods

Krzysztof Żuraw — Sun, 06 Aug 2023 11:19:11 +0000

If you are using React Hooks testing library to test your hooks remember to wrap hooks methods in the act.

For example, if you try to run the test below:

import { renderHook } from "@testing-library/react-hooks";

test("test login", () => {
  const { result } = renderHook(() => useAuth());

  result.login();

  expect(result.user).toEqual({ token: "token", user: "Tom Smith" });
});

You will get this error message:

Warning: An update to TestComponent inside a test was not wrapped in act(...).

When testing, code that causes React state updates should be wrapped into act(...):

act(() => {
  /* fire events that update state */
});
/* assert on the output */

This ensures that you're testing the behavior the user would see in the browser. Learn more at https://reactjs.org/link/wrap-tests-with-act
    at TestComponent ()
    at Suspense
    at ErrorBoundary ()

To fix this you need to wrap the result.login call with the act:

-import { renderHook } from "@testing-library/react-hooks";
+import { renderHook, act } from "@testing-library/react-hooks";

test("test login", () => {
  const { result } = renderHook(() => useAuth());

- result.login();
+ act(() => {
+     result.login();
+ });

  expect(result.user).toEqual({ token: "token", user: "Tom Smith" });
});

Composition vs props in React

Krzysztof Żuraw — Sat, 08 Jul 2023 15:27:08 +0000

I recently was adding support for dynamic data (meaning loaded from API) to the design system component. I started as usual - add new props indicating that for example, the Combobox component is loading or that it has its input value changed so I can hook into that and ask API. I added them to Combobox directly so I have more or less those props on the component level:

<Combobox loading={true} onInputValueChanged={callAPI} />

At first look, it seems like this component is ok - it has all props it needs to work. But can I do better? What about having a new component for this case? So I will have:

<Combobox /> // static data

<DynamicCombobox loading={true} onInputValueChanged={callAPI} /> // dynamic data

Why it is better? I think mainly because it follows React principle of composition. I can have a base combobox that shares functionality between static and dynamic. Another pro is that in the second case, it is harder to make the impossible state possible. What does it mean? If static Combobox does not have a loading prop I can't mess with it and set it to true when there is no call to API.

There is one more question: how do I share common parts between Combobox and DynamicSelect? I think there are at least 2 options:

BaseCombobox component - it will have all common parts of combobox: input, list of items to select, etc.
common functions, CSS classes - it is more granular as you compose your component from small pieces rather than full component

Polymorphic components in React

Krzysztof Żuraw — Sat, 20 May 2023 14:07:32 +0000

While I was working on the design system I knew I wanted to use polymorphic components as the foundation of it. It turns out that are a couple of approaches that you can use to create one. I will review them in this post.

Dessert Box

As I wrote in a blog post about polymorphic components with vanilla extract I was looking for a way to create polymorphic components with vanilla extract. I was recommended to check out the dessert box library. It uses a concept of vanilla-extract sprinkles and connect them together with polymorphic Box component.

After a couple of months of using it, I can say that it works fine. It is not perfect, but it is good enough. I like that you can import Box and construct your own components on top of it. Thanks to that it is way easier for users of your design system to use it.

The biggest problem is that you have weak typing of HTML attributes when using the dessert box. What does it mean? Let's say you have this Box defined:

export const Form = () => {
  return <Box as="form">// rest of the form</Box>;
};

You can pass any prop to <Box as="form"> right now - it can be onSubmit handler (which you may need) or type="text" (which made no sense in this context).

Radix asChild

Component library Radix is using a different approach. They have asChild utility. Let's say you have this component:

import * as Label from "@radix-ui/react-label";
import { Text } from "../Text"; // your design system component

<Label.Root className="LabelRoot" htmlFor="firstName" asChild>
  <Text>First name</Text>
</Label.Root>;

By passing asChild prop you are telling Radix to pass all its props to the child component. It is really handy because you can use your design system components without any wrappers. You also get better typing than with Box from dessert box from HTML attributes as TypeScript will know if you type="text" defined on <input/> component or not. The downside? You need to make sure that your component takes ref. You also get a bit of mess in your code which can be misleading for people who are not familiar with Radix.

CVA approach

There is a new library called Class Variance Authority - (CVA for short). While this is more of a replacement for vanilla-extract recipe I think it is worth mentioning here. What if you could export your styles as a recipe and use them in your components instead of using as or asChild?
For example:

import { button } from "./components/button"; // CVA styles

export const Button = ({ children }) => {
  return (
    <button className={button} type="submit">
      {children}
    </button>
  );
};

You get the best of both worlds - you have strong typing of HTML attributes and the composability of HTML tags. This seems like a nice idea but I have to test it in real world scenario.

Summary

I think that all of the approaches for creating polymorphic components have their pros and cons. I think that I will stick with the dessert box for now, but I will keep an eye on CVA and Radix asChild.

Sharing configs between Storybook and Vite

Krzysztof Żuraw — Sat, 06 May 2023 09:54:17 +0000

I have a project that is using Vite.js as a bundler with Storybook to have visual testing of components. I recently updated Storybook from version 5 to 7. Here are a couple of things I had to do to make it work.

Firstly you have to know that Storybook in version 7 will merge project vite.config.js to its own. What does it mean? It means that all your plugins will work out of the box with Storybook but on the other hand, you need to make sure that your paths in vite.config.js are correct. By correct I mean they should be absolute, not relative. Why? Let's say that you have your vite plugin configured to look for index.tsx file like this: entry: "./index.tsx" - it will work in your project but not in Storybook. It won't work because Storybook will look for index.tsx from its directory (by default in the .storybook folder), not from the root of your project. So you have to make sure that your paths are absolute. How to do this? You can use the path module from Node.js. Here is an example:

import { resolve } from "path";

export default defineConfig({
  plugins: [
    viteHtml({
      entry: resolve(__dirname, "index.tsx"),
    }),
  ],
});

Another issue that I found is that not all plugins will work with Storybook. For example, @vitejs/plugin-react-swc will not work with Storybook 7 - you can see the GitHub issue for details. What you can do to fix this? You can use the solution provided in the issue and remove the plugin from the config when running Storybook. Here is a code example:

import react from "@vitejs/plugin-react";
import { withoutVitePlugins } from "@storybook/builder-vite";

const config = {
  // the rest of the config
  async viteFinal(config) {
    config.plugins = await withoutVitePlugins(config.plugins, [
      "vite:react-swc",
    ]);

    return mergeConfig(config, {
      plugins: [react()],
    });
  },
};

Other than those two issues migrating to Storybook 7 was quite nice. Storybook has even a nice codemod to migrate from storiesOf to the new CSF format. That is all for today and I hope this will help you to migrate your project to Storybook 7.

Auto update readme on GitHub with Deno

Krzysztof Żuraw — Sun, 23 Apr 2023 13:58:34 +0000

GitHub has this nice feature where you can have a readme file in the repository named after your GitHub handle and it will be displayed on your profile page. I used to have this file automatically generated by a script that would fetch my latest blog posts and display them in the readme. I used Paweł solution and it worked fine.

I used to run this workflow every week on Sundays with a GitHub Action schedule](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule). Unfortunately recently it started failing - it turns out that switching to Astro broke the RSS structure. As I was fixing the script I decided to completely rewrite it with Deno.

I choose Deno because I wanted out-of-the-box support for TypeScript. One of the objectives of the rewrite was to have better handling of errors when iterating through the RSS feed. To accomplish that I've used Zod.

You can see the result in the snippet below:

import { z } from "https://deno.land/x/zod@v3.21.4/mod.ts";

const ResponseSchema = z
  .array(
    z.object({
      title: z.string(),
      url: z.string().url(),
    })
  )
  .nonempty();

const response = await fetch("https://krzysztofzuraw.com/blog.json");
const blogPosts = ResponseSchema.parse(await response.json());

const markdownPosts = blogPosts
  .map(({ title, url }) => `- [${title}](${url})`)
  .join("\n");

const openTag = `<!-- FEED-START -->`;
const closeTag = `<!-- FEED-END -->`;
const filePath = "./README.md";

const readme = await Deno.readTextFile(filePath);
const indexBefore = readme.indexOf(openTag) + openTag.length;
const indexAfter = readme.indexOf(closeTag);
const readmeContentChunkBreakBefore = readme.substring(0, indexBefore);
const readmeContentChunkBreakAfter = readme.substring(indexAfter);

const readmeNew = `${readmeContentChunkBreakBefore}\n${markdownPosts}\n${readmeContentChunkBreakAfter}`;

await Deno.writeTextFile(filePath, readmeNew);

console.log("Readme updated! 🎉");

I did a couple of changes to the script. I decided to add a new JSON page to Astro - it contains the last 3 blog posts - you can see the code here. I fetch blog.json and validate it using Zod. To be honest I'm impressed by this library - I previously used it only for form field validation but it works great for validating API responses as well.

I also found out that there is nifty Deno GitHub Action that I can use to set up the Deno environment in CI and that Deno has something like package.json called deno.json - it allows you to specify dependencies and scripts. I've used it to set up deno task.

The last change was to run this script not on the schedule but to trigger it when I push any changes to the blog repository. It works well but there is one caveat though - Netlify deployment runs on its own (via the GitHub app) and GitHub action runs too early to catch the changes. I poke around the internet to see if there was a way to trigger GitHub Action after Netlify deployed my blog but I didn't find anything officially supported by Netlify. I decided for now that I can live with that and I will just run this script when I or Renovate merge changes to the master. Maybe I will find a better solution in the future.

Forem: Krzysztof Żuraw

CSS aspect ratio property

Branded Types in TypeScript: techniques

1. Using a Type Wrapper

2. Using JavaScript Classes / Objects

3. Using Zod’s `brand()` Method

Summary

Recommended read

Error modelling

Lukasz Ostrowski for Saleor Commerce ・ May 29 '25

Dynamic Configuration for MCP Servers Using Environment Variables

Problem

Solution

Using the Script in MCP Clients

Summary

Custom metrics using @vercel/otel

Problem

Solution

DynamoDB access modeling for multi-tenant services

Problem

Modelling Approach

Access Patterns

Data Structure

DynamoDB Table Design

Primary Key (PK)

Sort Key (SK)

Benefits of This Design

Implementation Example

Summary

How to link a local npm dependency with pnpm

How you properly test your React hook methods

Composition vs props in React

Polymorphic components in React

Dessert Box

Radix asChild

CVA approach

Summary

Sharing configs between Storybook and Vite

Auto update readme on GitHub with Deno

Forem: Krzysztof Żuraw

CSS aspect ratio property

Branded Types in TypeScript: techniques

1. Using a Type Wrapper

2. Using JavaScript Classes / Objects

3. Using Zod’s brand() Method

Summary

Recommended read

Error modelling

Lukasz Ostrowski for Saleor Commerce ・ May 29 '25

Dynamic Configuration for MCP Servers Using Environment Variables

Problem

Solution

Using the Script in MCP Clients

Summary

Custom metrics using @vercel/otel

Problem

Solution

DynamoDB access modeling for multi-tenant services

Problem

Modelling Approach

Access Patterns

Data Structure

DynamoDB Table Design

Primary Key (PK)

Sort Key (SK)

Benefits of This Design

Implementation Example

Summary

How to link a local npm dependency with pnpm

How you properly test your React hook methods

Composition vs props in React

Polymorphic components in React

Dessert Box

Radix asChild

CVA approach

Summary

Sharing configs between Storybook and Vite

Auto update readme on GitHub with Deno

3. Using Zod’s `brand()` Method