DEV Community: Piotr Kulpinski

How I Built a Custom MCP Server for a Next.js App (Real Example)

Piotr Kulpinski — Fri, 30 Oct 2026 10:04:16 +0000

A custom MCP server is a server you build for your own app, so AI agents can use your product the way you do. I built one for Dirstarter, the Next.js directory boilerplate I sell (so yes, I'm biased about the example). An agent connected to it can take a URL, create a listing, fill in its copy and favicon from the website, pick categories and tags, and schedule it for the next free publish day.

This post is the real MCP server example I wish I'd found when I started. Most results for "MCP server example" are hello-world templates with an echo tool. Below is a production setup: two servers in one Next.js app, the code that turns existing API procedures into tools, the safety rules, and a real agent session with the numbers.

What a custom MCP server is (and when you need one)

MCP (Model Context Protocol) is the open standard AI clients use to call tools on other services. Claude, ChatGPT, Cursor and Claude Code all speak it. A server lists its tools, each with a name, a description and an input schema. The agent reads that list and decides which tools to call.

You need a custom one when the useful actions live in your own product. Ready-made servers already cover GitHub, Notion and Stripe. Nobody else can expose "schedule this listing for the next free publish day" in your app.

For a directory website, the use case is obvious. The real cost of running a directory is curation: finding tools, writing descriptions, sorting categories. OpenAlternative takes me 2-3 hours a week to maintain, and adding listings is the repetitive part of that. An agent with the right tools adds one in under a minute.

The example: two servers in one Next.js app

Dirstarter runs two MCP servers, because there are two different audiences:

Server	URL	Who calls it	Sign-in	What it can do
Public	`/mcp`	AI assistants answering their users	None	Search and read published listings
Admin	`/api/mcp`	Your own agent (Claude Code, Cursor)	Bearer secret	Add, edit, enrich and schedule content

The public server lets assistants recommend listings when someone asks for software. The admin server is where agents do the work. Splitting them keeps every write action behind a secret, and lets the public side stay small and read-only.

Turning existing procedures into MCP tools

This is the decision that saved the most time. I didn't write a second API for agents. Dirstarter's server code is a set of typed oRPC procedures, the same ones the admin UI calls. Any procedure becomes an MCP tool by adding one meta.mcp entry:

schedule: adminWrites
  .meta({
    mcp: {
      name: "schedule_tool",
      description:
        "Schedule a tool for publication. Without `publishedAt`, it takes the next free slot: the first publish day after today that no other scheduled tool holds.",
      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
      defaults: { notifyOwner: false },
    },
  })
  .input(toolScheduleSchema)
  .handler(async ({ input }) => {
    // the same handler the admin UI calls
  }),

At startup, a small registry walks the router and collects every procedure with meta.mcp. It converts each Zod input schema to the JSON Schema an MCP client expects, with z.toJSONSchema().

The procedure's permission decides which server lists the tool. If a guest is allowed to call it, it goes on the public server. Everything else goes on the admin server. A procedure with no permission defaults to admin, so nothing leaks to the public side by accident.

When an agent calls a tool, the server runs the procedure itself through the normal middleware. Permissions, rate limits, emails and webhooks behave exactly as they do when I click the button in the admin. There's nothing to keep in sync.

Serving MCP from a Next.js route handler

Both servers are stateless. Each request builds a fresh server with the official TypeScript SDK (@modelcontextprotocol/server), handles the call and returns. No sessions, no long-lived connections, so it runs fine on serverless hosting.

The public route only adds rate limits before handing the request to the SDK:

const handler = createStatelessMcpHandler(() =>
  createMcpServer({ audience: "public", user: null }),
)

export async function POST(request: Request) {
  const { error } = await tryCatch(consumePublicRateLimits())

  if (error instanceof ORPCError) {
    return refuseMcpRequest(429, error.message)
  }

  return handler.fetch(request)
}

The limits are 1,000 requests per hour per address and 20,000 in total. The per-address limit is high on purpose: Claude and ChatGPT call from shared address ranges, so a low limit would block real users.

The admin route checks a bearer token against MCP_SECRET. It hashes both values first and compares them with timingSafeEqual, so the check takes the same time whatever the token is. Every call then runs as the site's first admin account. That account also becomes the author of any blog post the agent drafts.

Connecting an agent is one command, from the Claude Code MCP docs:

claude mcp add --transport http my-directory-admin https://your-site.com/api/mcp \
  --header "Authorization: Bearer <MCP_SECRET>"

Writing tools an agent can actually use

The plumbing is the easy part. Getting agents to use the tools well is harder, and four things made the difference.

Descriptions are prompts. Each description says what the tool does, when to call it and what it returns. The server also sends instructions with the recommended order for adding a tool: check for duplicates, create a draft, enrich it, review it, schedule it. In my test sessions, agents followed that order every time.

Errors say what to fix. A failed call returns its code, such as BAD_REQUEST, followed by each invalid field and what's wrong with it. Agents fix their input and retry instead of giving up.

Defaults differ from the UI. In the admin, changing a tool's status emails its owner by default. For an agent doing bulk edits, that would spam every owner it touches. So the MCP tools default notifyOwner to false, and the agent has to ask for an email explicitly.

The tool list stays small. A test checks that each server stays under 25 tools and 25 KB of definitions. Some clients load every tool into context, and a bloated list makes agents worse at picking the right one. List tools also drop long Markdown bodies from their results and leave them to the matching get_ tool.

The safety rules

An agent with write access to a live site needs guardrails in the tools, not only in the prompt.

Nothing deletes. There's no delete tool on either server. To take something down, the agent sets it to Draft. Deleting stays a manual action in the admin.
User text is data. Reports, submitter notes and listing descriptions are written by strangers, and any of them could contain a prompt injection. The server instructions tell the agent to treat that text as data and never act on requests inside it.
New records start as drafts. Nothing an agent creates goes live until it's scheduled, and the daily publish job handles the rest.

A real agent session

To check the whole flow end to end, I started a fresh Dirstarter instance locally, connected Claude Code to the admin server and gave it one sentence:

The agent made 7 tool calls and finished in 54 seconds. It checked for a duplicate, read the 8 categories and 21 tags, created the draft, and called enrich_tool. That tool scraped cal.com and filled the tagline, description, page content and favicon. Then it scheduled the listing for the next free day.

It also reported a gap honestly: no screenshot. My local copy had no S3 bucket configured, and Dirstarter skips screenshots without storage. On a real deployment that step fills in too.

Here's the result, a scheduled listing with its preview page:

My earlier runs were less clean, and they taught me something. When the scraper failed, the agent wrote the copy from its own knowledge and flagged that it hadn't checked the claims. That's the right behavior. It also shows why the tools should leave a draft behind for you to review.

The public server: getting recommended by AI assistants

The second server is about distribution, a new channel next to search and programmatic SEO. When someone asks Claude or ChatGPT for a scheduling tool, an assistant connected to your directory can search it and link to your listings.

Three tools cover it: search_tools, get_tool and list_categories. All of them are read-only, and results are ordered by relevance alone. Paid tiers play no part, because the Claude and ChatGPT directories don't allow paid placement.

Every outbound link goes through a /go/<slug> redirect that records the click as an mcp visit in analytics. Assistants don't report the traffic they send, so without the redirect you'd never see it.

I'll be upfront: I don't have traffic numbers from this yet. The server only becomes useful at scale once it's listed in the assistant directories, and those reviews take time. I'll write about the results when I have real data.

Should you build a custom MCP server?

If your app has actions people repeat every week, yes. It works with any stack that has typed server code, and most of the best Next.js templates have that already. The work is smaller than it looks when you already have typed procedures, because the MCP layer is mostly a registry and two route handlers. The hard part is tool design: clear descriptions, safe defaults and no destructive tools.

If you're building a directory, you don't have to build it from scratch. Dirstarter ships both servers, and the MCP setup guide covers connecting an agent in a few minutes. If you're still at the planning stage, start with how to build a directory website, then come back to this once you have listings to manage.

Originally published on the Dirstarter blog.

7 Open-Source Tools for Better Website Analytics

Piotr Kulpinski — Tue, 14 Jan 2025 14:22:33 +0000

If you are running a website, SaaS, or online business, having a good analytics tool is important for understanding your website's performance and growth. Analytics tools can give you valuable information about user behavior, where your traffic comes from, and how people engage with your site.

In 2025, open-source analytics tools have become more powerful and affordable, giving businesses of all sizes a way to track and analyze their data without breaking the bank.

Let's dive into the list:

1. Umami

If you're looking for a modern and easy-to-use open-source analytics tool that helps you analyze and manage your website traffic, Umami is the perfect one. Umami shows you who visits your site, where they come from, and what they do. It offers tools to track custom events, spot trends, and analyze user behavior, making it great for growing your website.

You can get started in just minutes with no complicated setup. It's also privacy-friendly and works well for businesses of any size. You can use it for free until you reach a limit of 100,000 events per month.

If you want clear, real-time insights without the clutter, Umami is the solution you need. It's the best alternative for Fathom Analytics, Kissmetrics, and Google Analytics.

It's the best alternative for Fathom Analytics, Google Analytics, Kissmetrics, and MixPanel

Project Link: Umami

2. OpenPanel

OpenPanel is an easy-to-use, open-source analytics tool that helps you monitor and understand how people interact with your website or app. It offers a strong alternative to Mixpanel & Plausible without the high costs.

With real-time analytics and clear dashboards, you can quickly see what works and what doesn't. It includes features like user tracking, event analysis, and detailed reports to help you make better decisions. This tool respects your privacy while providing key information in an easy-to-use format. Easily check visitor details, referrals, popular pages, entry and exit points, device usage, sessions, bounce rate, duration, and geographical data. Use these insights to make informed decisions effortlessly.

It's perfect for developers and businesses that want control and flexibility.

It's the best alternative for Fathom Analytics, Segment, Google Analytics, Amplitude, Kissmetrics, and MixPanel

Project Link: OpenPanel

3. Countly

This tool is a little bit different from others, as it provides insights based on how your users interact with your products. It's an All-in-One analytic tool for mobile, website, and desktop apps.

Countly helps you understand how people use your apps and websites. It gathers data from all your platforms and shows you what works well and what doesn't. With Countly, you can make smart decisions to improve your business without needing many different tools. It protects your privacy, so your data stays safe.

You can customize Countly to fit your needs by creating special dashboards or adding extra features. Countly makes analytics simple and powerful for businesses of all sizes.

It's the best alternative for June, Fathom Analytics, Google Analytics, Amplitude, Kissmetrics, and MixPanel

Project Link: Countly

4. Swetrix

This analytics tool is special because, unlike other tools, it provides additional information such as performance, sessions, errors, uptime, funnels, and alerts for your website.

Swetrix keeps your data private and doesn't use cookies, unlike other tools. It is open source, so you can customize it to meet your needs. Whether you have a small website or a large online store, Swetrix makes analytics simple and clear.

Swetrix is the best choice for monitoring and growing your business if you want to avoid using complicated tools.

It's the best alternative for Fathom Analytics, Google Analytics, MixPanel, and Kissmetrics

Project Link: Swetrix

5. Matomo

Matomo prioritizes the safety and confidentiality of user information while helping you understand how visitors interact with your website. Unlike other analytics platforms, Matomo gives you full ownership of your data, reducing any privacy concerns.

It's user-friendly and doesn't rely on tracking cookies, making it easier to comply with privacy regulations. You can use Matomo to monitor visitor activity, gain insights into their interests, and make informed decisions to improve your website.

If you want to grow your website without compromising privacy, Matomo is an excellent choice, trusted by over a million users.

It's the best alternative for Fathom Analytics, Google Analytics, Google Tag Manager, and Kissmetrics

Project Link: Matomo

6. Plausible

A straightforward and private solution for monitoring website traffic is Plausible Analytics. It doesn't use cookies, so there won't be any prominent banners, and it's quite light, so it won't slow down your website.

While adhering to privacy regulations like the GDPR, you can know precisely where your traffic is coming from and how users are interacting with your website. It's simple to set up, open source, and even makes it easy to move away from Google Analytics.

Plausible is the best option if you value privacy and want lucid insights.

It's the best alternative for Fathom Analytics, Google Analytics, Google Workspace, and Kissmetrics

Project Link: Plausible

7. Trench

Trench is an open-source tool that makes it super easy to analyze and manage big data in real-time. This tool is only 3 months old and is supported by Y-Combinator.

It is fast, scalable, and works well for tracking events and user actions on websites or apps. Built with strong technologies like Kafka and Clickhouse, it handles large data volumes effectively. Trench is GDPR-compliant, so you can trust it to protect your data privacy. You can choose to self-host it or use their cloud service, making it flexible for your needs.

It is perfect for developers who want full control and powerful analytics.

It's the best alternative for June, Segment, Amplitude, Kissmetrics, Full Story, and MixPanel

Project Link: Trench

Conclusion

I hope these open-source projects are useful to you. You can look into OpenAlternative if they don't meet your demands or if you're searching for other projects. It offers a wide range of free and open-source tools as substitutes for paid and expensive software out there.

Thanks for reading!

Written by Mohit Vaswani.

How to post a link with embed card on Bluesky with JavaScript

Piotr Kulpinski — Wed, 11 Dec 2024 16:19:47 +0000

As Bluesky continues to gain popularity, more tools are being developed around it. One of the most popular applications is post scheduling and automation.

However, Bluesky's API currently doesn't offer a direct way to post links with OpenGraph cards. This can be a challenge for users who want to share links with attractive previews.

In this tutorial, I'll show you how to use JavaScript to post a link on Bluesky with a embed card. This method works around the API limitation, allowing you to share links more effectively.

Let's get started!

Posting on Bluesky using JavaScript API

Working with Bluesky API is pretty simple. The docs are pretty good. First up, we need to install the @atproto/api package from NPM:

npm install @atproto/api

Next, we create an instance of the Bluesky Agent and login with your Bluesky credencials.

I recommend creating a new App Password for your Bluesky account, rather than using your main password. This will make it easier to revoke access if needed and keep your main account secure. Also make sure to set the BLUESKY_USERNAME and BLUESKY_PASSWORD environment variables in your project.

import { AtpAgent } from "@atproto/api"

const getBlueskyAgent = async () => {
  const agent = new AtpAgent({
    service: "https://bsky.social",
  })

  await agent.login({
    identifier: process.env.BLUESKY_USERNAME!,
    password: process.env.BLUESKY_PASSWORD!,
  })

  return agent
}

Once you have the agent, you can use it to post to Bluesky which is pretty straightforward.

/**
 * Send a post to Bluesky
 * @param text - The text of the post
 */
export const sendBlueskyPost = async (text: string, url?: string) => {
  const agent = await getBlueskyAgent()

  await agent.post({ text })
}

And there you have it, you just sent a post to Bluesky. Unfortunately, even if you include a link in the text of your post, it isn't automatically converted into an anchor link. We'll fix that shortly.

Detect Faceted Links on Bluesky Automatically

When you include a link in your post text on Bluesky, it isn't automatically turned into an anchor link. Instead, it appears as plain text.

To fix this, you need to detect the links and convert them into faceted links.

While there are manual methods to achieve this, fortunately, ATProto provides a RichText class that can automatically detect links and convert them into faceted links.

import { RichText } from "@atproto/api"

/**
 * Send a post to Bluesky
 * @param text - The text of the post
 */
export const sendBlueskyPost = async (text: string) => {
  const agent = await getBlueskyAgent()
  const rt = new RichText({ text })
  await rt.detectFacets(agent)

  await agent.post({
    text: rt.text,
    facets: rt.facets,
  })
}

That's great, but we still need to add the embed card to the post. Let's do that next.

Creating an Embed Card on Bluesky

Including a link in your post is great, but it's even better if you can add a embed card.

To achieve this, we need to use the Website card embed feature of Bluesky. Essentially, you add an embed key to your post that includes, at a minimum, a URL, title, and description.

There are several ways to obtain the required data. If you know it at the time of posting, you can simply hardcode it. Otherwise, you can scrape the URL to gather the title, description, and image.

However, I find the easiest way is to use the Dub.co Metatags API to fetch the URL metadata and then create the embed card from that. Let's see how that works.

type Metadata = {
  title: string
  description: string
  image: string
}

/**
 * Get the URL metadata
 * @param url - The URL to get the metadata for
 * @returns The metadata
 */
const getUrlMetadata = async (url: string) => {
  const req = await fetch(`https://api.dub.co/metatags?url=${url}`)
  const metadata: Metadata = await req.json()

  return metadata
}

We created a simple function that fetches the URL metadata and then returns the data in a clear format.

Next, let's create a function that uses the metadata to upload the image to Bluesky and then create the embed card.

const getBlueskyEmbedCard = async (url: string | undefined, agent: AtpAgent) => {
  if (!url) return

  try {
    const metadata = await getUrlMetadata(url)
    const blob = await fetch(metadata.image).then(r => r.blob())
    const { data } = await agent.uploadBlob(blob, { encoding: "image/jpeg" })

    return {
      $type: "app.bsky.embed.external",
      external: {
        uri: url,
        title: metadata.title,
        description: metadata.description,
        thumb: data.blob,
      },
    }
  } catch (error) {
    console.error("Error fetching embed card:", error)
    return
  }
}

Once we have the embed card, we can add it to the post.

export const sendBlueskyPost = async (text: string, url?: string) => {
  const agent = await getBlueskyAgent()
  const rt = new RichText({ text })
  await rt.detectFacets(agent)

  await agent.post({
    text: rt.text,
    facets: rt.facets,
    embed: await getBlueskyEmbedCard(url, agent),
  })
}

Now we have a function that sends a post to Bluesky with an embed card.

Complete Example

Hopefully, if you have followed along, you should have a complete code by now. If not, here is the complete code that you can copy and paste into your project. It:

Creates a Bluesky agent
Fetches the URL metadata
Creates an embed card
Sends a post to Bluesky with the embed card and automatically detects faceted links

import { AtpAgent, RichText } from "@atproto/api"

type Metadata = {
  title: string
  description: string
  image: string
}

/**
 * Get the URL metadata
 * @param url - The URL to get the metadata for
 * @returns The metadata
 */
const getUrlMetadata = async (url: string) => {
  const req = await fetch(`https://api.dub.co/metatags?url=${url}`)
  const metadata: Metadata = await req.json()

  return metadata
}

/**
 * Get the Bluesky embed card
 * @param url - The URL to get the embed card for
 * @param agent - The Bluesky agent
 * @returns The embed card
 */
const getBlueskyEmbedCard = async (url: string | undefined, agent: AtpAgent) => {
  if (!url) return

  try {
    const metadata = await getUrlMetadata(url)
    const blob = await fetch(metadata.image).then(r => r.blob())
    const { data } = await agent.uploadBlob(blob, { encoding: "image/jpeg" })

    return {
      $type: "app.bsky.embed.external",
      external: {
        uri: url,
        title: metadata.title,
        description: metadata.description,
        thumb: data.blob,
      },
    }
  } catch (error) {
    console.error("Error fetching embed card:", error)
    return
  }
}

/**
 * Get the Bluesky agent
 * @returns The Bluesky agent
 */
const getBlueskyAgent = async () => {
  const agent = new AtpAgent({
    service: "https://bsky.social",
  })

  await agent.login({
    identifier: process.env.BLUESKY_USERNAME!,
    password: process.env.BLUESKY_PASSWORD!,
  })

  return agent
}

/**
 * Send a post to Bluesky
 * @param text - The text of the post
 * @param url - The URL to include in the post
 */
export const sendBlueskyPost = async (text: string, url?: string) => {
  const agent = await getBlueskyAgent()
  const rt = new RichText({ text })
  await rt.detectFacets(agent)

  await agent.post({
    text: rt.text,
    facets: rt.facets,
    embed: await getBlueskyEmbedCard(url, agent),
  })
}

I hope you found this tutorial helpful and that you will consider using it in your own projects.

Happy posting!

Top 5 Open-Source Projects for Developers

Piotr Kulpinski — Wed, 04 Dec 2024 14:19:29 +0000

If you’re a developer looking to improve your productivity, check out some outstanding open-source projects I’ve found. They can enhance your skills and streamline your workflow effectively.

These projects are made by skilled developers for the entire community. Whether you’re just starting or have years of experience, there’s something for you.

They will help you with a variety of tasks like —

Track, improve, and build better apps.
Find and Fix code errors faster than ever.
Connect and organize your data for smarter decisions.
See and fix issues in your app while keeping your data secure.
Make your website analytics much easier and shareable.

Let’s take a look at the top five projects in detail.

1. PostHog

This project is a secret weapon for developers who want to build awesome websites and apps that users love to use.

It helps you track what people are doing on your website, find ways to make it better and fix problems quickly. All of your data is in one place, and you have complete control over it.

It’s super powerful, easy to use, and makes building successful & scalable apps feel easy.

It’s the best alternative for Fathom Analytics, Segment, Amplitude, Optimizely, June, and MixPanel

Many big companies are satisfied customers of Posthog.

Project Link: Posthog

2. Sentry

When your app has bugs, it can be frustrating and time-consuming to fix them. But with Sentry, you can resolve errors quickly and easily.

It helps you find what went wrong in your codebase and shows you how to fix it. You can track issues, replay user sessions, and even see what your users are experiencing — all in one place.

It’s like having an expert programmer for your coding. You won’t need to guess or waste time anymore. You can create clean and effective websites faster than ever.

It’s the best alternative for Datadog, BetterStack and LogRocket

Project Link: Sentry

3. Airbyte

This project helps you make your data more useful, no matter where it is stored. It connects data from different apps and platforms, allowing you to use it in smart ways, such as enhancing AI or improving your business.

It’s open-source, so anyone can use it. Also, it’s easy to set up, secure and works with tons of tools.

Whether you’re a data wizard or just starting out, this makes managing and using your data a breeze.

It’s the best alternative for Fivetran, Matillion, and Supermetrics

Project Link: Airbyte

4. OpenReplay

OpenReplay is like a time machine for your apps. It lets you watch exactly what your users are doing on your website or app — like a replay of their sessions.

You can find and fix bugs to make your website run better. The best part is that you can host it yourself, keeping all your data safe and private. It has great features like product analytics, DevTools, and co-browsing to help users in real time.

Honestly, it’s like having a perfect tool to make your app the best.

It’s the best alternative for Mixpanel, New Relic, BetterStack, Kissmetrics, Amplitude, June, LogRocket, and FullStory

Project Link: OpenReplay

5. Plausible

Plausible is the cool, privacy-friendly analytics your website needs. It’s a perfect alternative to Google Analytics that shows you all the necessary stats about your site — like visitors, clicks, and where people are coming from.

It’s lightweight, so it won’t slow down your site, and it doesn’t use cookies or need those unnecessary consent banners. Also, it’s open-source, so you can trust it’s safe and transparent.

If you care about privacy and want clean, no-fuss data, Plausible is your perfect match!

It’s the best alternative for Mixpanel, Google Analytics, Kissmetrics, Fathom Analytics and Google Workspace

Project Link: Plausible

I hope you find these open-source projects helpful. If they don’t fit your needs or if you’re looking for more projects, you can explore OpenAlternative. It includes a variety of open-source alternative tools to paid software.

Thanks for reading!

Written by Mohit Vaswani.

Supercharge Your Number Inputs with Custom Step Sizes

Piotr Kulpinski — Fri, 26 Apr 2024 21:33:41 +0000

The <input type="number"> element provides a convenient way to handle numeric input in web forms. You can set bounds with the min and max attributes, and users can press the up and down arrow keys to increment or decrement the value by the specified step size. However, what if you want to allow users to adjust the value using different step sizes?

By default, the step attribute not only determines the increment/decrement amount but also clips the value to the nearest multiple of the step. For example, if you have an input with a value of 5 and a step of 10, pressing the up arrow key will set the value to 10 (the nearest multiple of the step) instead of 15 (5 + 10).

How to build a better number input

In this article, we'll explore how to enhance the functionality of number inputs to support custom step sizes. We'll implement the following features:

↑/↓ – adjusts the value by the specified step size (1 if step is not specified).
Shift+↑/↓ – adjusts the value by step multiplied by 10.
Alt+↑/↓ – adjusts the value by step divided by 10.
Ctrl/Cmd+↑/↓ – adjusts the value by step multiplied by 100.
If the input is empty, the value is calculated based on the min attribute (0 if min is not specified).

Let's dive into the implementation!

Helper Functions

First, let's define some utility functions that we'll use throughout the implementation.

const parseNumericValue = (value?: string | number | null) => {
  if (value === undefined || value === null) return undefined
  const parsed = Number.parseFloat(value.toString())

  return Number.isNaN(parsed) ? undefined : parsed
}

The parseNumericValue function takes a value (which can be a string, number, or null) and parses it as a floating-point number. If the value is undefined or null, it returns undefined. If the parsing fails, it also returns undefined.

This function will be useful for parsing the min, max, step, and current value of the input elements.

const preciseRound = (value: number, decimals = 2) => {
  const factor = Math.pow(10, decimals)

  return Math.round((value + Number.EPSILON) * factor) / factor
}

The preciseRound function rounds a number to a specified number of decimal places. It uses the Number.EPSILON constant to handle floating-point precision issues.

const keepNumberInRange = (value: number, min?: number, max?: number) => {
  if (min !== undefined && max !== undefined) {
    return Math.min(Math.max(value, min), max)
  }
  if (min !== undefined) {
    return Math.max(value, min)
  }
  if (max !== undefined) {
    return Math.min(value, max)
  }

  return value
}

The keepNumberInRange function ensures that a given number stays within the specified min and max bounds. I like to use reusable utility functions like this to keep the code clean and maintainable.

Implementing the Key Up Handler

Here's the main event handler function that will be called when the user presses the up or down arrow keys on a number input:

import { KeyboardEvent } from "react"

const handleKeyUp = (e: KeyboardEvent<HTMLInputElement>) => {
  if (!["ArrowUp", "ArrowDown"].includes(e.key)) {
    return
  }

  const target = e.currentTarget
  const direction = e.key === "ArrowUp" ? 1 : -1
  const min = parseNumericValue(target.getAttribute("min"))
  const max = parseNumericValue(target.getAttribute("max"))
  const step = parseNumericValue(target.getAttribute("step")) || 1
  const value = parseNumericValue(target.value) || min || 0
  const increment = step * (e.metaKey ? 100 : e.shiftKey ? 10 : e.altKey ? 1 / 10 : 1)

  const newValue = preciseRound(value + direction * Math.max(increment, 0.1), 2)

  if (newValue !== value) {
    target.value = keepNumberInRange(newValue, min, max)
    e.preventDefault()
  }
}

// Usage: <input type="number" onKeyUp={handleKeyUp} />

Let's break down the code:

We check if the pressed key is either "ArrowUp" or "ArrowDown". If not, we return early.
We get the current target input element and determine the direction based on the pressed key (+1 for "ArrowUp", -1 for "ArrowDown").
We parse the min, max, and step attributes of the input element using the parseNumericValue utility function.
We parse the current value of the input using parseNumericValue or fallback to the min value or 0 if the input is empty.
We calculate the increment based on the modifier keys: Ctrl/Cmd multiplies the step by 100, Shift multiplies it by 10, Alt divides it by 10, and the default is 1.
We calculate the new value by adding the product of the direction and the increment to the current value, using the preciseRound utility function to handle floating-point precision.
If the new value is different from the current value, we update the input value using the setInputValue function, ensuring it stays within the specified min and max range.
Finally, we call e.preventDefault() to prevent the default browser behavior.

With this implementation, your number inputs will have the desired supercharged behavior, allowing users to quickly adjust values using different step sizes based on the modifier keys they press.

You can easily integrate this code into your project by attaching the handleKeyUp event handler to your number input elements.

Happy coding!

How to Build Dynamic Breadcrumbs in Remix

Piotr Kulpinski — Fri, 29 Mar 2024 20:30:46 +0000

In Remix, building dynamic breadcrumbs that reflect your route hierarchy is straightforward. This tutorial will guide you through leveraging the useMatches and handle capabilities to achieve this.

We'll also cover how to add schema metadata to your breadcrumbs for better SEO and social sharing.

The Basics

Breadcrumbs are a navigation aid that helps users understand their current location within a website. They typically appear horizontally at the top of a page and show the hierarchy of the current page in relation to the site structure.

Here's an example of what breadcrumbs code could look like:

<ol itemscope itemtype="https://schema.org/BreadcrumbList">
  <li itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
    <a href="https://example.com/" itemprop="item">
      <span itemprop="name">Home</span>
    </a>
    <meta itemprop="position" content="1" />
  </li>

  <li itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
    <a href="https://example.com/posts" itemprop="item">
      <span itemprop="name">Posts</span>
    </a>
    <meta itemprop="position" content="2" />
  </li>

  <li itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
    <a href="https://example.com/posts/slug" itemprop="item">
      <span itemprop="name">Post Title</span>
    </a>
    <meta itemprop="position" content="3" />
  </li>
</ol>

Now, let's see how to build dynamic breadcrumbs in Remix.

Defining the Breadcrumbs Components

Let's start by creating the necessary component that we'll later use to render the breadcrumbs.

We'll need a Breadcrumbs component to render the list of breadcrumbs and a BreadcrumbsItem component to render each breadcrumb item.

Start by defining a wrapper component that will list all of the breadcrumbs.

// app/components/Breadcrumbs.tsx
import { UIMatch, useMatches } from "@remix-run/react"
import { Fragment, HTMLAttributes } from "react"

type BreadcrumbMatch = UIMatch<
  Record<string, unknown>,
  { breadcrumb: (data?: unknown) => JSX.Element }
>

export const Breadcrumbs = ({ ...props }: HTMLAttributes<HTMLElement>) => {
  const matches = (useMatches() as unknown as BreadcrumbMatch[]).filter(
    ({ handle }) => handle?.breadcrumb
  )

  return (
    <ol
      itemScope
      itemType="https://schema.org/BreadcrumbList"
      className="flex flex-wrap items-center gap-2.5"
      {...props}
    >
      {matches.map(({ handle, data }, i) => (
        <Fragment key={i}>
          <li
            className="contents"
            itemProp="itemListElement"
            itemScope
            itemType="https://schema.org/ListItem"
          >
            {i > 0 && <span className="text-sm">/</span>}
            {handle.breadcrumb(data)}
            <meta itemProp="position" content={`${i + 1}`} />
          </li>
        </Fragment>
      ))}
    </ol>
  )
}

In the example above, we're using the useMatches hook to get the current route matches. We then filter the matches to only include those that have a breadcrumb handle. We will define this handle in the routes where we want to include a breadcrumb. We then iterate over the matches and render the breadcrumb component for each match.

You may have noticed that we're also passing a data prop to the handle.breadcrumb function. This is because the breadcrumb handle can accept data from the route loader. We'll see how to pass data to the breadcrumb handle in the next section.

Next, let's define the BreadcrumbsItem component that we'll use to render each breadcrumb item.

// app/components/BreadcrumbsItem.tsx
import { Link } from "@remix-run/react"
import { HTMLAttributes } from "react"

export const BreadcrumbsItem = ({ children, ...props }: HTMLAttributes<HTMLElement>) => {
  return (
    <Link to={props.href} itemProp="item" {...props}>
      <span itemProp="name">{children}</span>
    </Link>
  )
}

Now that we have our components, let's define the breadcrumbs in our routes.

Defining the Breadcrumbs handles in the Routes

In the routes where you want to include breadcrumbs, you need to define a breadcrumb handle that will render the breadcrumb item.

For example, let's define the following routes:

/ - Home
/posts - Posts
/posts/$slug - Post Details

// app/routes/index.tsx
import { BreadcrumbsItem } from "~/components/BreadcrumbsItem"

export const handle = {
  breadcrumb: () => <BreadcrumbsItem to="/">Home</BreadcrumbsItem>,
}

export default function Index() {
  return <h1>Home</h1>
}

// app/routes/posts/index.tsx
import { BreadcrumbsItem } from "~/components/BreadcrumbsItem"

export const handle = {
  breadcrumb: () => <BreadcrumbsItem to="/posts">Posts</BreadcrumbsItem>,
}

export default function Posts() {
  return <h1>Posts</h1>
}

// app/routes/posts.$slug.tsx
import { json, type LoaderFunctionArgs } from "@remix-run/node"
import { useLoaderData } from "@remix-run/react"
import { BreadcrumbsItem } from "~/components/BreadcrumbsItem"

export const handle = {
  breadcrumb: (data: { title: string; slug: string }) => (
    <BreadcrumbsItem to={`/posts/${data.slug}`}>{data.title}</BreadcrumbsItem>
  ),
}

export const loader = ({ params }: LoaderFunctionArgs) => {
  const post = {
    title: "Example Post",
    slug: "example-post",
  }

  return json(post)
}

export default function Post() {
  const { title } = useLoaderData<typeof loader>()

  return <h1>{title}</h1>
}

In the last route, we're using the loader function to fetch the post data. We then pass this data to the breadcrumb handle to render the breadcrumb item. This allows us to dynamically generate the breadcrumb item based on the post data.

Conclusion

Hopefully, this guide has helped you understand how to implement breadcrumbs in your Remix application.

If you're interested to see how breadcrumbs can be implemented in a real-world application, you can check out the OpenAlternative project, or check out the source code.

If you have any questions or need further clarification, feel free to reach out to me on Twitter.

Growing a side-project to 100k Unique Visitors in one week

Piotr Kulpinski — Tue, 19 Mar 2024 21:43:24 +0000

I'm a software engineer by trade, but I've always been interested in marketing and growth. I've been working on a various side projects for a while now, and I recently hit a major success: 100,000 unique visitors in one week.

Here's how I did it 👇

https://twitter.com/piotrkulpinski/status/1767108966603980866

The Idea

I was collecting a list of open-source software for a while. Mostly for my own use (to learn and reuse parts of the code), but I thought it would be cool to share it with others. I was also interested in learning more about SEO and growth, so I thought this would be a good project to experiment with.

I didn't want to spend a lot of time on it, so I decided to build it within 48 hours.

With such a short time frame, I had to be very selective about the features I wanted to include. I decided to build a simple listing with no search or filtering.

Curating the list

I started by expanding the list of open-source software. I used a combination of Google, Reddit, and GitHub to find the most popular open-source projects. I also used my own knowledge and experience to find lesser-known projects that I thought were worth including.

I didn't want to include every open-source project I could find. I wanted to keep the list high-quality and focused on the most popular, useful software and actively maintained projects. I collected about 70 projects in total.

Building the site

Astro was always on my list of things to learn. I've been using Remix and NextJS for a while, and I was interested in trying out a new framework. I decided it would be a good opportunity to build the site with it. This decision turned out to be a great one, as it saved me a lot of money on hosting costs later on.

While browsing the Astro documentation, I found out they have a pretty easy way to implement a View Transitions so I tought it would be a nice touch to the site.

For the backend, I opted for Airtable as a database. It's a simple, no-code solution that I've used before. It's not the most powerful database, but it's perfect for a project like this. I could easily add, edit, and delete records, and it has an embeddable form functionality that I used for user submissions.

Unfortunately, Airtable's API isn't the best for querying data, so I used a middleware service to turn the Airtable API into a GraphQL API. This allowed me to query the data in a more flexible way.

With the data and the site structure in place, I started building the site. I used Tailwind CSS for the styling, and I was able to build the site in about 12 hours. The good thing about having multiple projects under my belt is that I can reuse a lot of the code I've written before.

Building an Open Source listing, it was pretty obvious that I should open-source the code as well.

GitHub Data and Programmatic SEO

To make the site more useful, I decided to include some data from GitHub. I've built a scheduled Cloudflare Worker that's pulling the GitHub API data to fetch the number of stars, forks, and issues for each project.

I also pulled some related tags from each repo, like what programming language it's written in, and what it's related to (e.g. CMS, CRM, etc.). I then put this data into Airtable and used it to generate lots of pages for Programmatic SEO.

It's too early to tell if this will have a big impact on SEO, but I think it's a good idea to have a lot of pages for Google to index. It's already ranking for some very competitive keywords like "open source alternatives" so I think it may work pretty well.

Hosting

Since Astro is a static site generator, I could host the site for free on Cloudflare. I've never used Cloudflare before, but they've been pretty popular lately due to their free hosting and CDN. I was impressed with how easy it was to set up, and the performance was great.

I then picked the simplest name I could find and registered openalternative.co for $6.99.

Launch(es)

Twitter

Like always, I posted about it on Twitter. Given that I only had 900 followers and I usually tweet to the void, I didn't expect much. But to my surprise, the tweet got some attention. Nothing crazy, but it was a good start.

For the next few days I let it sit and see what happens. I was engaging with people on Twitter to get some feedback. One of such conversations was with Steven Tey who seemed to like the idea and decided to share it with his audience.

https://twitter.com/steventey/status/1765841867017437599

This was a huge boost for the site, as it got a lot of traffic from his tweet.

Product Hunt

I knew I had to keep the momentum going, so I decided to post it on Product Hunt the next day.

I still had some nice traffic to the site, so I've added a custom PH banner to the top of the site to let people know about the launch. I also posted about it on Twitter and LinkedIn.

With the help of the community, we were able to get 3rd place on the day of the launch with over 500 upvotes. This was one of the most successful PH launches I've ever had.

Hacker News

Knowing that the site was getting some attention, I decided to post it on Hacker News as well.

I had a feeling that it would do well on HN, as I thought it would be a good fit for the community, but I didn't expect it to get this good.

The post immediately got featured on to the front page and quickly climbed to claim the #1 spot on the site. It got over 150 upvotes and stayed on the front page for a few hours.

Being featured on Product Hunt is great, but #1 on Hacker News is a whole different level. The traffic was insane. I was getting thousands of visitors every hour.

In the same time, I was also posting about it on Reddit. I've posted it on a few subreddits, but the most successful one was on r/SelfHosted. It quicky got over 250 upvotes and a lot of comments.

Unfortunately, I made a mistake by trying to monetize some of the traffic by adding a Stripe Pay link to the site. For $97, a project could be featured on the top of the list. I thought it would be a good way to monetize the site, but it was a mistake. I got a lot of negative feedback and I quickly removed it.

Due to that, reddit users quickly turned on me and the site. I was getting a lot of negative comments and downvotes, and the post was removed from the subreddit.

Still, the traffic was great and I was able to get a lot of feedback from the community.

Summary

The site was a huge success. It got over 100,000 visitors in the first week, and it's still getting a few thousand visitors every day. It was a great experiment in launching a side project and growth, and I learned a lot from it.

Hopefully, you'll be able to take something away from this story and apply it to your own projects. If you have any questions or feedback, feel free to reach out to me on Twitter.

If you want to check out the site, you can find it at openalternative.co.