DEV Community: Hayyan Hami

Switch Docker Compose workspaces with dwork.

Hayyan Hami — Sat, 24 Oct 2026 00:00:00 +0000

Switching between development projects often means repeating a small checklist: stop the previous application's processes, resume the next database, wait for it to become usable, open a development terminal, and find the right browser tab. Docker Compose describes the containers, but that checklist can also include commands running on the host.

dwork records that workspace routine in a local configuration. It resumes existing Compose containers, waits for configured Docker health checks, launches approved terminal commands, and opens application URLs when they respond.

This walkthrough uses two independent projects and shows the boundary between their initial setup and everyday switching. The repository's Get started section and demo links a 42-second overview of the workflow. The steps below explain the configuration and lifecycle without requiring the video.

Start with two working projects

Suppose atlas and notebook are existing Next.js applications. Each has a PostgreSQL service in Compose and a dev package script that runs next dev:

~/projects/
  atlas/
    compose.yaml
    package.json
    dwork.yml
  notebook/
    compose.yaml
    package.json
    dwork.yml

The applications run on the host; their databases run in containers. Atlas uses port 3000 and Notebook uses 3001. Their existing database configuration must also use distinct host ports if both databases might run together. Adapt these names, scripts, and ports to your projects.

Complete each application's documented dependency installation, environment configuration, container creation, and migrations first. For these example projects, the container creation step is:

cd ~/projects/atlas
docker compose -p atlas-dev up -d postgres

cd ~/projects/notebook
docker compose -p notebook-dev up -d postgres

These are initial Docker Compose setup commands , separate from dwork. They assume each Compose file already defines a postgres service. Add any build, seed, or migration steps required by the application, then verify that each application works manually.

dwork does not call docker compose up. It uses docker start and docker stop on existing containers. It does not create, rebuild, pull, or remove containers, networks, or volumes. If you later remove a database container or change its stored environment, use your normal Compose setup to create or recreate it before switching with dwork again.

Use unique Compose project names. Here, atlas-dev and notebook-dev identify separate container groups; atlas and notebook will become shorter dwork registration names. They serve different purposes.

Install dwork and check the prerequisites

The documented source installer is:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/hayyaun/dwork/main/install.sh)"

It installs the current main source for your user, with isolated Python dependencies, including PyYAML. It requires Git, Make, curl, and Python with venv support: Python 3.10 or newer on Linux/WSL2, or 3.13 or newer on macOS. It does not install system prerequisites. Review the installer and installation options before running downloaded code; release packages are available there too. Add the printed PATH setting if your shell does not already find ~/.local/bin.

Container workspaces need the Docker CLI, access to a running Engine, and Compose supporting config --no-interpolate --no-env-resolution --format json. Terminal commands use Bash or Zsh configured as SHELL. The sample also needs each application's own Node.js dependencies installed.

Visible terminals require a supported desktop launcher: GNOME Terminal, Konsole, Xfce Terminal, or xterm on Linux; Apple Terminal on macOS; or Windows Terminal and Windows PowerShell on WSL2. Linux needs a graphical session. The terminal guide describes launcher selection. Keeping a launcher out of the shared YAML lets each developer choose locally, for example with DWORK_TERMINAL=konsole.

Check the installed command before continuing:

dwork --version
dwork --help

This article follows the current documentation. Avoid assuming that every field on main exists in an older package. For example, the optional top-level dwork name field is documented as newer than v0.6.0; this walkthrough uses explicit registration names instead.

Give the database a real health check

A running container is not necessarily a ready database. dwork's terminal health gate reads Docker's health status, so the existing PostgreSQL service needs a health check. For a PostgreSQL image providing pg_isready, a typical addition to that service is:

services:
  postgres:
    # Keep the project's existing image, environment, ports, and volumes.
    healthcheck:
      test: ["CMD-SHELL", 'pg_isready -U "$$POSTGRES_USER" -d "$$POSTGRES_DB"']
      interval: 5s
      timeout: 3s
      retries: 12

This assumes the service already sets POSTGRES_USER and POSTGRES_DB. The doubled dollar signs let the container shell expand those variables instead of Compose interpolating them on the host. Apply the change through the project's normal Compose workflow. dwork cannot add a health check to an existing container merely by reading the updated file.

That check establishes database availability. It does not prove that migrations ran or that the application has the expected schema. Keep those requirements in the application's setup process. See Docker's health-check reference for the underlying status behavior.

Save a repeatable workspace configuration

Create atlas/dwork.yml beside compose.yaml:

# yaml-language-server: $schema=https://raw.githubusercontent.com/hayyaun/dwork/main/schemas/dwork.schema.json
version: 1

compose:
  enabled: true
  files: [compose.yaml]
  services: [postgres]

terminals:
  - title: Atlas development
    command: [npm, run, dev, --, --port, "3000"]
    window: new
    wait_for:
      healthy: [postgres]
      timeout: 180

browsers:
  - url: http://localhost:3000
    wait_for:
      timeout: 60

This manages only the existing postgres containers in the selected Compose project. Other services in that project remain untouched. Omit services only if you intend dwork to manage all existing containers belonging to it.

The terminal command is an argument list. It matches a Next.js dev script and passes --port 3000 through npm. For another framework, replace it with that project's actual command. Quote numeric arguments such as "3000": command arguments must be strings. Use an existing script for pipelines or compound shell operations.

Reuse this configuration in notebook/dwork.yml, changing the title to Notebook development and both port values to 3001. The common structure is intentionally ordinary project configuration. Each file can be committed with its application and adjusted as the workflow changes. dwork does not merge multiple dwork files.

Paths such as compose.files and terminal cwd are relative to dwork.yml. If the host application lives in frontend/, add cwd: frontend to the terminal entry. A Compose override can be listed explicitly as files: [compose.yaml, compose.dev.yaml]; explicit Compose file CLI arguments or COMPOSE_FILE take precedence.

Validate, register, and switch

Use the same Compose identity that created the containers when checking and registering each project:

cd ~/projects/atlas
dwork validate -p atlas-dev
dwork doctor -p atlas-dev
dwork register atlas -p atlas-dev

cd ~/projects/notebook
dwork validate -p notebook-dev
dwork doctor -p notebook-dev
dwork register notebook -p notebook-dev

dwork list
dwork switch atlas --dry-run
dwork switch atlas

validate checks configuration, paths, and Compose references. doctor checks the environment, including Docker and launcher prerequisites. Neither launches the application. Registration saves the directory and Compose selection without starting or stopping workloads. The saved switch can then be invoked from another directory; it does not change your calling shell's directory.

Read the preview and switch confirmation before applying the plan. Individual terminal and browser entries also ask for approval by default. Their separate prompts can be disabled deliberately with confirm: false on each entry; the sample retains the defaults.

Now switch projects:

dwork switch notebook --dry-run
dwork switch notebook

For an ordinary unlocked switch on the same Docker target, the sequence is:

Stop outgoing commands tracked by dwork, then eligible outgoing managed containers.
Start existing destination containers that are created or exited.
Pass all configured Docker health gates before opening any terminal.
Launch approved terminal commands, then process browser entries in order.

Notebook's browser entry waits for its URL to return HTTP 200–399 before dispatching it to the browser. This is a separate readiness check from PostgreSQL health: the database must be ready before the app starts, and the app must respond before the page opens. Redirect responses count as ready without being followed. A successful response is not an application test.

Only registered workspaces are eligible for outgoing shutdown. Unregistered projects stay running. Registering both examples is therefore part of making this switching routine work.

Know what remains open and what can fail

When you switch away, dwork stops its tracked foreground command and leaves the visible terminal at a shell prompt. Commands you subsequently start manually in that shell are outside its tracking. Programs that daemonize or escape the tracked process group need their own lifecycle management.

Browser windows remain open. The browser decides whether a new URL reuses a tab or window. On WSL, URLs open through Windows; readiness is checked from the Linux distribution, so it does not independently verify Windows firewall or localhost forwarding. See the browser behavior and networking notes.

Repeated activation launches another copy of each approved configured task and opens the URLs again. dwork does not deduplicate an already-running development server. Preview first and avoid treating activation as a status command.

A missing required health-check container blocks activation before outgoing projects stop. Later health timeouts or launch failures can leave completed container changes and already-launched tasks in place. There is no automatic rollback. Inspect the reported state with dwork status -p notebook-dev from Notebook's directory and preview the next action before retrying.

Changing a Compose project name, file selection, or managed service selection requires explicit re-registration with the intended options. Saved registrations are local user state, while dwork.yml describes the project workflow. Keep secrets out of registration arguments.

Keep shared work running when needed

Sometimes both applications need to stay available. Named startup is additive:

dwork up atlas notebook --dry-run
dwork up atlas notebook

Unlike a switch, named up leaves other workspaces running. It still launches approved tasks, so account for the duplication behavior above. Named startup requires CLI 0.5.0 or newer.

For shared infrastructure that should survive switches, use locked: true in its dwork config or a local dwork lock NAME until you explicitly unlock it. The existing DWORK_KEEP_PROJECTS setting also protects exact Compose project names. Protection applies to tracked commands as well as containers; membership in a reusable named group does not itself provide a lock.

To inspect and stop eligible registered workloads when finished:

dwork down --dry-run
dwork down

The confirmation names the affected work. Containers and registrations remain available for the next switch, while locked and unregistered workloads stay running. Docker itself and the WSL VM are not shut down, and stopping workloads does not promise a particular amount of host-visible memory recovery.

The useful starting point is one correctly configured project, one successful preview, and one deliberate switch. Then register the second project and reuse the same routine. The dwork repository, configuration reference, and worked examples cover adaptations such as separate backend/frontend directories and host-only workspaces.

Dynamic Head-Out Image Box Using React + Tailwind CSS

Hayyan Hami — Sat, 11 Jan 2025 19:48:14 +0000

Need a quick UI boost? 🚀 Here’s a simple React + Tailwind CSS snippet to create a stylish Head-Out Image Box.

Code

// HeadOutImage.tsx
interface IProps {
  alt: string;
  src: string;
}

export default function HeadOutImage({ alt, src }: IProps) {
  return (
    <div className="group aspect-[7/9] h-auto w-full flex-[0_0_auto] self-start overflow-hidden border-b-2 border-white pt-20">
      <div className="size-full border-2 border-b-0 border-white bg-red-400/0 transition-colors duration-500 group-hover:bg-red-400/85" />
      <Image
        alt={alt}
        src={src}
        className="absolute -bottom-24 h-auto w-full border-2 border-transparent transition-all duration-500 ease-in-out group-hover:-bottom-20"
      />
    </div>
  );
}

Using group class and modifier, we can achieve cool effects as above. Copy, paste, done! 🖼️✨ You can also adjust displacement and customize it in a way you like!

Create an Amazing Interactive Tour in React – A Complete Guide

Hayyan Hami — Sat, 11 Jan 2025 18:17:41 +0000

Creating an engaging and interactive tour is a powerful way to onboard users, highlight key features, and enhance the user experience in your React application. 🌟 Whether you’re introducing new functionality, guiding first-time users, or providing contextual tips, a well-designed interactive tour can leave a lasting impression. 💡 In this complete guide, we’ll walk you through the process step by step—from planning and designing your tour to implementing it with best practices. 🛠️ By the end, you’ll have all the tools and knowledge needed to create a polished, user-friendly tour that makes your app shine and keeps your users coming back for more. 🎉

To achieve this, we need to create a Tour component. This component will accept a list of steps and navigate through them sequentially.

Define Interfaces

When defining type interfaces for each step, a query selector is used to locate the area that will be highlighted. Additionally, each step includes a title for the description box and content for the description itself.

// Tour.tsx
export interface ITourStep {
  q: string; // Query selector string
  title: string; // Title for the description box
  content: ReactNode; // Content to be displayed as the description
}

interface IProps {
  items: ITourStep[] | null; // List of tour steps. null indicates inactive state
  onComplete: () => void; // Callback to trigger on tour finished 
}

export default function Tour({ steps, onComplete }: IProps) {
  ...
}

Add Elements

There are two key elements: one focuses on highlighting the target area while dimming the surrounding region, and the other is the bubble that displays the title, description, and buttons.

// Tour.tsx

...

export default function Tour({ steps, onComplete }: IProps) {
  const focus = useRef<HTMLDivElement>(null!);
  const bubble = useRef<HTMLDivElement>(null!);
  const content = useRef<HTMLSpanElement>(null!);
  const [index, setIndex] = useState(0); // active index

  ...

  return (
    <>
      <div
        ref={focus}
        className="pointer-events-none fixed left-0 top-0 z-[99] hidden size-56 rounded-lg border-2 border-white/10 opacity-0 shadow-[0_0_0_9999px_#000000f2]"
      />
      <div
        ref={bubble}
        className="fixed left-0 top-0 z-[100] hidden w-64 flex-col gap-3 rounded-xl bg-white p-4 opacity-0"
      >
        <span ref={content} className="text-justify text-sm text-black" />
        <button onClick={onNext} className="text-green-400">
          {!!active && active < items.length ? "Next" : "Done"}
        </button>
      </div>
    </>
  );
}

Final Code

The final step is to add animations and functionality to the component. This includes displaying step 1 when the steps change, updating the current step when the "Next" button is clicked, and hiding the tour when the steps are set to null. Additionally, we need to ensure the focused area scrolls into view and that the bubble is positioned optimally, adapting to all screen sizes for a responsive design.

// Tour.tsx
"use client";

import { useGSAP } from "@gsap/react";
import clsx from "clsx";
import gsap from "gsap";
import { TextPlugin } from "gsap/all";
import { useRef, useState } from "react";

gsap.registerPlugin(TextPlugin);

export interface ITourStep {
  q: string; // Query selector string
  title: string; // Title for the description box
  content: ReactNode; // Content to be displayed as the description
}

interface IProps {
  items: ITourStep[] | null; // List of tour steps. null indicates inactive state
  onComplete: () => void; // Callback to trigger on tour finished 
}

export default function Tour({ steps, onComplete }: IProps) {
  const focus = useRef<HTMLDivElement>(null!);
  const bubble = useRef<HTMLDivElement>(null!);
  const content = useRef<HTMLSpanElement>(null!);
  const [index, setIndex] = useState(0); // active index

  useGSAP(async () => {
    const inactive = !index || !steps || index > steps.length;

    gsap.to([bubble.current, focus.current], {
      opacity: inactive ? 0 : 1,
      display: inactive ? "non" : "flex",
      duration: 0.7,
    });

    if (inactive) return;
    const step = steps[index - 1];
    const el = document.querySelector(step.q);
    if (!el) return;
    el.scrollIntoView({ block: "center", inline: "start" });
    const { width: bw } = bubble.current.getBoundingClientRect();
    const { width, height: h0, x, y } = el.getBoundingClientRect();
    const [vw, vh] = [window.innerWidth, window.innerHeight];
    const sm = vw < lg;
    const height = h0 > vh ? vh - oy2 : h0;
    const right = x + width / 2 > vw / 2;
    const bigH = height > vh / 2;
    const bx = sm ? -ox : !right ? width + ox2 : -(bw + ox2);
    const by = sm ? (!bigH ? height + oy2 : height / 2 + oy2) : -oy;
    gsap.to(bubble.current, { left: x, top: y, x: bx, y: by });
    const [w, h] = [width + ox2, height + oy2];
    const [fx, fy] = [x - ox, y - oy];
    gsap.to(focus.current, { width: w, height: h, left: fx, top: fy });
    gsap.to(content.current, { text: step.content });
  }, [index, steps]);

  const onNext = () => {
    if (index > steps.length - 1) return setIndex(0);
    setIndex((i) => i + 1);
  };

  return (
    <>
      <div
        ref={focus}
        className="pointer-events-none fixed left-0 top-0 z-[99] hidden size-56 rounded-lg border-2 border-white/10 opacity-0 shadow-[0_0_0_9999px_#000000f2]"
      />
      <div
        ref={bubble}
        className="fixed left-0 top-0 z-[100] hidden w-64 flex-col gap-3 rounded-xl bg-white p-4 opacity-0"
      >
        <span ref={content} className="text-justify text-sm text-black" />
        <button onClick={onNext} className="text-green-400">
          {!!active && active < items.length ? "Next" : "Done"}
        </button>
      </div>
    </>
  );
}

Usage

const tour: ITourStep[] = [
  {
    q: "#box-1",
    title: "Title 1",
    content: "Content 1",
  },
  {
    q: "#box-2",
    title: "Title 2",
    content: "Content 2",
  },
];

export default function App() {
  const [steps, setSteps] = useState<ITourStep[] | null>(null);

  const onStart = () => setSteps(tour);
  const onComplete = () => setSteps(null);

  return (
    <div id="home">
      <div id="box-1">...</div>
      <div id="box-2">...</div>
      <button onClick={onStart} />
      <Tour steps={steps} onComplete={onComplete} />
    </div>
  );
}

🎉 Congratulations! 🎉

You’ve successfully built an amazing interactive tour in React! 🚀 By following this guide, you’ve created a user-friendly feature that not only enhances your app's usability but also delivers a delightful experience for your users. From planning the steps to implementing animations and responsive design, you've covered everything needed to make your tour both functional and engaging.

Now it’s time to take your app to the next level. Whether you're onboarding new users or guiding them through advanced features, your interactive tour is ready to shine! ✨

Thank you for reading, and happy coding! 💻🎨

Next 14 Rate Limiting made easy

Hayyan Hami — Fri, 10 Jan 2025 15:59:52 +0000

Rate limiting plays a critical role in preventing abuse by controlling the number of requests that a single user is allowed to make within a given time frame. To keep track of requests and corresponding IP addresses, this information must be stored in memory for fast access and a better response time. ⛔✋

Deploying your Next.js app on Vercel's serverless or edge environments allows for great speed and scalability. These infrastructures handle requests individually, spinning up lightweight instances as needed to deliver very fast responses. This architectural design does come with one major limitation, though: data stored in the memory of a single instance isn't accessible to other instances, since each instance runs in a stateless way.

To solve this, we reach out in most cases to external solutions like Redis, an in-memory high-performance database. One of the services that complement Vercel perfectly is Upstash Redis, enabling shared, low-latency data access across instances.

With that foundation set, let's look at the implementation!

Method 1: Upstash Redis 🙌

In your Vercel project page, go to Storage tab.
Click on Create Database button, then select Upstash for Redis:

After creating the db, you'll see the list of secrets.
Keep in mind that these secret variables are already bound to your vercel project and you don't need to redefine them, but for local development you will need to copy them into your .env.local file.

Don't forget to put this line in your .gitignore:

.env*.local

Install the following modules:

$ npm i @upstash/redis @upstash/ratelimit

Create a ratelimit instance and use it

// route.ts
import { Ratelimit } from "@upstash/ratelimit";
import { Redis } from "@upstash/redis";

const rateLimiter = new Ratelimit({
  limiter: Ratelimit.fixedWindow(1, "60 s"),
  redis: Redis.fromEnv(),
  analytics: true,
  prefix: "@upstash/ratelimit",
});

const getIP = (req: Request) => {
  const ip =
    req.headers.get("cf-connecting-ip") || 
    req.headers.get("x-forwarded-for") ||
    undefined;
  return Array.isArray(ip) ? ip[0] : ip;
};

export async function POST(req: Request) {
  // ...
  // Here we check if limit hit! 👇
  const { success } = await rateLimiter.limit(ip || "unknown");
  if (!success) return Response.json({ error: "Too many requests" }, { status: 429 } );
  // ...
}

And done!

Method 2: Tile38 self-hosted

This method is not relied on third-party services with their limitations but requires you to have a server.

Install docker on your server if not installed already.

Run Tile38 docker with custom configs

$ docker run --name tile38 -d -p 9851:9851 tile38/tile38

Config ufw-docker to open related port

$ sudo ufw-docker allow tile38

Or you can use reverse-proxy on nginx if you want to keep it behind a domain.

Now that everything is set, it's time for usage.
To bypass the limitations, we can create our own adapter as below:

// route.ts
import { Tile38 } from "@iwpnd/tile38-ts";
import { Ratelimit } from "@upstash/ratelimit";

// Tile38 HTTP API URL
const tile38 = new Tile38("http://your_server_ip:9851");

// Custom adapter for Tile38
const customTile38Adapter = {
  // Custom function to simulate Lua script execution via HTTP API
  evalsha: async (script: any, keys: any, args: any) => {
    try {
      const key = keys[0]; // Assuming we're using a single key for rate-limiting
      const value = args[0]; // The value used for rate-limiting
      const { ok } = await tile38.jSet("ratelimit", key, "root", value);
      return { success: ok };
    } catch (error) {
      return { success: false };
    }
  },
  get: async () => null,
  set: async () => null,
};

// Initialize the rate limiter with Tile38 as the adapter
const ratelimit = new Ratelimit({
  redis: customTile38Adapter, // Using the custom adapter
  limiter: Ratelimit.fixedWindow(1, '10s'), // 10 requests per 10 seconds
});

...

Congratulations! 🎉 You’ve unlocked the power of combining Vercel’s serverless capabilities with Upstash Ratelimit. This setup will not only elevate your app’s performance but also open the door to building highly scalable, fast, and reliable applications. With this powerful foundation, your Next.js app is ready to handle whatever comes next—smoothly and efficiently. 🚀

Animate Web Sections with useSection Hook

Hayyan Hami — Sun, 07 Jul 2024 13:08:50 +0000

Sometimes, you may want to trigger an animation for a specific section based on whether the user has switched to that section. Here’s how you can achieve this:

Usage

By using this hook, you can run animations based on scroll direction while maintaining consistency between transitions. In certain scenarios, you may want to trigger different animations depending on the section you’re navigating from or to or even the direction if going forward or backward. We'll be building this hook in this post.

// SecondSection.tsx
import { Section } from './enums.ts'

export default function SecondSection() {
  const { active } = useSection(
    () => ({
      section: Section.Second,
      enter(back) {
        // fade-in
        if(!back) ...  // when coming from previous (1 -> 2)
        else ...       // when coming from next (3 -> 2)
      },
      leave(back) {
        // fade-out
        if(!back) ...  // when going forward (2 -> 3)
        else ...       // when going backward (2 -> 1)
      },
    }),
    [],
  );

  return ...
}

Configuration

1. Define Sections as an Enum

First, create an enum to represent your sections. For example:

// enums.ts
enum Section {
  First,
  Second,
  Third,
}

2. Global State Management

To manage global state, consider using a library like zustand. Here’s an example of setting up a store:

// store.ts
import { create } from 'zustand'

const useStore = create((set) => ({
  section: Section.First,
  setSection: (section) => set((state) => ({ section })),
}))

3. Watch Section Changes

Create a custom hook called usePrevious that stores the previous value and triggers an effect when the section changes:

// usePrevious.ts
import { useEffect, useRef } from "react";

export default function usePrevious<T extends any[]>(fn: (prev: T) => any, deps: T) {
  const previousDepsRef = useRef<T>(deps);

  useEffect(() => {
    const eject = fn(previousDepsRef.current);
    previousDepsRef.current = deps;
    return eject;
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, deps);
}

4. Create the useSection Hook:

Finally, implement the useSection hook with four events: enter, leave, enterBack, and leaveBack. This hook will help you manage section transitions:

// useSection.ts
import { DependencyList, useMemo, useState } from "react";
import usePrevious from "@/hooks/usePrevious";
import { useStore } from "@/store";
import { Section } from "@/ts/enums";

type Config = {
  section: Section;
  enter?: (from: Section, back: boolean) => Function | void;
  leave?: (to: Section, back: boolean) => Function | void;
};

export default function useSection(
  getConfig: () => Config,
  deps: DependencyList,
) {
  const section = useStore((s) => s.section);

  // eslint-disable-next-line react-hooks/exhaustive-deps
  const config = useMemo(getConfig, deps);
  const [target] = useState<Section>(config.section);

  // same as useEffect but with previous values
  usePrevious<[Section, Config | undefined]>(
    ([fromSection]) => {
      if (section === target) {
        const back = target < fromSection;
        return config.enter?.(fromSection, back);
      }
      if (fromSection === target) {
        const back = target > section;
        return config.leave?.(section, back);
      }
    },
    [section, config],
  );

  const active = useMemo(() => section === target, [section, target]);

  return { section, active };
}

Feel free to explore the implementation on my portfolio website. Let me know if you have any questions!