DEV Community: Yasin ATEŞ

Atomic Design in Practice: React and Storybook from Scratch 🧩

Yasin ATEŞ — Tue, 07 Apr 2026 19:17:20 +0000

Frontend projects can get messy fast as they scale. That's exactly where Atomic Design comes in — a methodology for building UIs in a layered, controlled way. In this article, we'll cover Atomic Design from the ground up, then translate it into a real mini-project using React and Storybook.

🧩 What Is Atomic Design?

Atomic Design is a methodology that proposes building UIs by starting from small, reusable building blocks and progressively composing them into larger structures. Brad Frost was the first to systematize this approach, and today it's especially common in design system work.

Why does it matter? Because in most projects, components start out innocent enough and then spiral into chaos with names like HeaderFinal, ProductCardNew, and ProductCardUpdated. Atomic Design gives us a shared, unambiguous vocabulary to fight that entropy.

Atomic Design is organized around five layers:

★ Atom
The smallest UI building blocks at the HTML level. A button, input, label, or a tiny badge all live here.

★ Molecule
Small groups of atoms working together to perform a meaningful task. A search box (input + button) is a classic example.

★ Organism
Larger, more meaningful UI sections composed of molecules and atoms. Header, ProductCard, and Sidebar are good examples.

★ Template
Defines the skeleton of a page. Focuses on layout, not content.

★ Page
A template filled with real data. This is what the user actually sees.

Worth pausing here: Atomic Design is not just a folder-naming convention. The real goal is to separate UI responsibilities across layers and draw clear boundaries between each one.

🤔 Why Does It Matter?

Imagine you're building an e-commerce app. Your homepage, category page, campaign page, and favorites screen all share very similar cards, buttons, filter areas, and header structures.

If you don't organize these pieces systematically from the start, you'll soon find yourself carrying four slightly different versions of the same component. That slows down refactoring, makes testing harder, and stretches onboarding time.

Here's why I reach for this approach:

★ Reusability increases
An atom or molecule written once can be reused across different pages.

★ Maintenance cost drops
When a design change comes in, you don't have to hunt through every file.

★ Team communication gets clearer
The moment you can say "Is this an organism or a molecule?" you've established a shared language.

★ It pairs beautifully with Storybook
Developing and testing components in isolation becomes much easier.

★ Building a design system becomes tractable
Your UI library grows in a controlled way, not a chaotic one.

Bottom line: Atomic Design doesn't just bring order, it brings long-term velocity.

⚛️ How Should You Think About Atomic Design in React?

React is a component-based JavaScript library for building UIs, which makes it a natural fit for Atomic Design. Here's how the layers map onto React:

★ Atom = Pure, small, self-contained component
Examples: Button, Input

★ Molecule = Small, purposeful UI combination
Example: SearchBox

★ Organism = A larger block responsible for a specific feature area
Examples: Header, ProductCard

★ Template = The layout skeleton of a page
Example: MainLayout

★ Page = The screen that works with real data and state
Example: HomePage

One critical point: not every large component has to be an organism. Sometimes a clean, simple Card stays comfortably at the molecule level. When deciding on a layer, look at responsibility, not size.

🛠️ Setting Up the Project

Enough theory, let's get our hands dirty. We'll scaffold a base React project first, then add Storybook to enable a component-driven development workflow.

Step 1: Scaffold the React project

Vite is a frontend toolchain that provides a fast dev server and a modern build experience. The commands below create a new React project and spin it up locally.

npm create vite@latest atomic-design-react -- --template react
cd atomic-design-react
npm install
npm run dev

Key parts:

★ npm create vite@latest generates the new project scaffold.
★ --template react selects the preconfigured React template.
★ npm run dev starts the development server.

Expected result: A blank React application running in your browser.

Step 2: Add Storybook

Storybook is a tool that lets you develop and document UI components in isolation, independent of your application.

npx storybook@latest init

Once installation is complete, launch Storybook with:

npm run storybook

A few things worth noting:

★ The init command analyzes your project structure and auto-generates the necessary config files.
★ npm run storybook lets you view components in a dedicated, sandboxed environment.
★ This setup is especially powerful for verifying each atomic layer in isolation.

Expected result: The Storybook UI opens in your browser and displays some example stories.

📁 Setting Up the Folder Structure

A messy folder structure will wear down even the best component architecture over time.

The structure below is a solid starting point for mid-sized projects.

src/
  components/
    atoms/
      Button.jsx
      Input.jsx
    molecules/
      SearchBox.jsx
    organisms/
      Header.jsx
      ProductCard.jsx
    templates/
      MainLayout.jsx
  pages/
    HomePage.jsx
  data/
    products.js
  App.jsx
  main.jsx
  styles.css

A few things to pay attention to:

components/atoms holds the smallest, most general-purpose pieces.
molecules combines atoms but stays at a controlled size.
organisms contains larger UI blocks that carry real business value.
templates defines layout, not real page data.
pages is where actual state and data flow begins.

🧪 Atom-Level Components

At the atom level, the goal is simple: write small, reusable, self-contained pieces. Components here should be as independent as possible.

`Button.jsx`

// src/components/atoms/Button.jsx
export default function Button({
  children,
  variant = "primary",
  type = "button",
  onClick,
}) {
  return (
    <button
      type={type}
      className={`button button--${variant}`}
      onClick={onClick}
    >
      {children}
    </button>
  );
}

Key points:

variant = "primary" gives the button a default style type.
children keeps the button content flexible.
At the atom level, the job is purely to render. No business logic.

`Input.jsx`

// src/components/atoms/Input.jsx
export default function Input({
  value,
  onChange,
  placeholder = "Search...",
  ...props
}) {
  return (
    <input
      className="input"
      value={value}
      onChange={onChange}
      placeholder={placeholder}
      {...props}
    />
  );
}

Key points:

...props keeps the input flexible for future use cases.
value and onChange come from the outside, so the component is controlled.
No unnecessary state at the atom level.

💡 The simpler your atoms, the more freedom you have at higher layers.

🧬 Molecule-Level Components

At the molecule layer, we're building small but purposeful combinations. A standalone Input is just a field. A SearchBox represents a specific user intent.

`SearchBox.jsx`

// src/components/molecules/SearchBox.jsx
import Button from "../atoms/Button";
import Input from "../atoms/Input";

export default function SearchBox({ query, onQueryChange, onSearch }) {
  return (
    <div className="search-box">
      <Input
        value={query}
        onChange={(event) => onQueryChange(event.target.value)}
        placeholder="Search products"
      />
      <Button onClick={onSearch}>Search</Button>
    </div>
  );
}

Design decisions worth calling out:

SearchBox holds no internal state. It delegates control to the page layer.
Input and Button remain atoms; they simply come together here.
This component now does meaningful work on the page, which is why treating it as a molecule makes sense.

🏗️ Organism-Level Components

At the organism layer, we're building more significant UI sections. Components here represent a distinct, recognizable region of the page.

`Header.jsx`

// src/components/organisms/Header.jsx
import Button from "../atoms/Button";
import SearchBox from "../molecules/SearchBox";

export default function Header({ query, onQueryChange, onSearch }) {
  return (
    <header className="header">
      <div className="header__brand">ShopSphere</div>
      <SearchBox
        query={query}
        onQueryChange={onQueryChange}
        onSearch={onSearch}
      />
      <Button variant="secondary">My Cart</Button>
    </header>
  );
}

Key things to notice:

★ Header is no longer a single atom or molecule. It's a larger UI section.
★ It uses both a molecule and an atom internally.
★ The brand area, search area, and cart action come together to form a functional region.

`ProductCard.jsx`

// src/components/organisms/ProductCard.jsx
import Button from "../atoms/Button";

export default function ProductCard({ product }) {
  return (
    <article className="product-card">
      <div className="product-card__emoji" aria-hidden="true">
        {product.emoji}
      </div>
      <h3 className="product-card__title">{product.title}</h3>
      <p className="product-card__description">{product.description}</p>
      <div className="product-card__footer">
        <strong>{product.price} TL</strong>
        <Button>Add to Cart</Button>
      </div>
    </article>
  );
}

Key points:

The product object gains real meaning at the organism level.
Button is reused as an atom.
The card represents a standalone, significant UI unit on the page, which is why it belongs at the organism level.

📐 Template and Page Layers

This is where most people get confused. Template and page are not the same thing.

Template defines the structure of a page.
Page is that structure filled with real data and state.

`MainLayout.jsx`

// src/components/templates/MainLayout.jsx
import Header from "../organisms/Header";

export default function MainLayout({
  query,
  onQueryChange,
  onSearch,
  children,
}) {
  return (
    <div className="layout">
      <Header
        query={query}
        onQueryChange={onQueryChange}
        onSearch={onSearch}
      />
      <main className="layout__content">{children}</main>
    </div>
  );
}

What makes this structure important:

★ children keeps the template flexible and composable.
★ MainLayout establishes layout but has no awareness of product data.
★ This separation pays real dividends as projects grow.

A template should be as content-agnostic as possible. Data, filtering logic, and page-level behavior belong in the page layer.

🛍️ Sample Project: Building a Mini E-Commerce UI

Now let's wire together all the layers we've built into a real working page.

Step 1: Create the mock product data

// src/data/products.js
export const products = [
  {
    id: 1,
    emoji: "⌨️",
    title: "Mechanical Keyboard",
    description: "Hot-swappable, compact keyboard with RGB support.",
    price: 2499,
  },
  {
    id: 2,
    emoji: "🖱️",
    title: "Gaming Mouse",
    description: "Lightweight body, high DPI, and low latency.",
    price: 1499,
  },
  {
    id: 3,
    emoji: "🎧",
    title: "Wireless Headset",
    description: "Long battery life with low-latency connectivity.",
    price: 3299,
  },
];

Why this matters:

We can test the page layer independently from a real API.
The same mock data can be reused in Storybook stories.
Data flow is easy to reason about during development.

Step 2: Write the `HomePage` component

// src/pages/HomePage.jsx
import { useMemo, useState } from "react";
import ProductCard from "../components/organisms/ProductCard";
import MainLayout from "../components/templates/MainLayout";
import { products } from "../data/products";

export default function HomePage() {
  const [query, setQuery] = useState("");

  const filteredProducts = useMemo(() => {
    return products.filter((product) =>
      product.title.toLowerCase().includes(query.toLowerCase())
    );
  }, [query]);

  const handleSearch = () => {
    console.log(`Searching for: ${query}`);
  };

  return (
    <MainLayout
      query={query}
      onQueryChange={setQuery}
      onSearch={handleSearch}
    >
      <section className="page-intro">
        <h1>Featured Products</h1>
        <p>A sample catalog screen built with the Atomic Design approach.</p>
      </section>
      <section className="product-grid">
        {filteredProducts.map((product) => (
          <ProductCard key={product.id} product={product} />
        ))}
      </section>
    </MainLayout>
  );
}

Most critical points:

Real state lives here. We're at the right layer.
Filtering logic is resolved at the page level.
MainLayout handles layout only; it doesn't manage data.

Step 3: Wire up the application entry point

// src/App.jsx
import HomePage from "./pages/HomePage";
import "./styles.css";

export default function App() {
  return <HomePage />;
}

Small file, but it matters:

App now renders the page-level screen.
Global styles are loaded from a single location.
The atomic layers are properly connected from top to bottom.

Step 4: Add minimal styles

/* src/styles.css */
:root {
  font-family: Inter, system-ui, sans-serif;
  color: #e2e8f0;
  background: #0f172a;
}

* {
  box-sizing: border-box;
}

body {
  margin: 0;
}

.layout__content {
  max-width: 1100px;
  margin: 0 auto;
  padding: 32px 20px;
}

.header {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 16px;
  padding: 20px;
  border-bottom: 1px solid #1e293b;
  background: #111827;
}

.header__brand {
  font-size: 20px;
  font-weight: 700;
}

.search-box {
  display: flex;
  gap: 12px;
  flex: 1;
  max-width: 520px;
}

.input,
.button {
  border-radius: 12px;
  border: 1px solid #334155;
  padding: 12px 16px;
}

.input {
  flex: 1;
  background: #0f172a;
  color: #e2e8f0;
}

.button {
  cursor: pointer;
  color: white;
  background: #2563eb;
}

.button--secondary {
  background: #334155;
}

.page-intro {
  margin-bottom: 24px;
}

.product-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  gap: 16px;
}

.product-card {
  padding: 20px;
  border: 1px solid #1e293b;
  border-radius: 18px;
  background: #111827;
}

.product-card__emoji {
  font-size: 40px;
  margin-bottom: 12px;
}

.product-card__footer {
  display: flex;
  align-items: center;
  justify-content: space-between;
  margin-top: 16px;
}

Worth noting:

The dark theme makes component boundaries more visible.
The product-grid layout lets you inspect card organisms comfortably.
Variant classes like button--secondary demonstrate the flexibility built at the atom level.

📝 I realized I've been defaulting to SCSS and CSS Modules in almost all my recent articles. For a real Storybook project I'd still go with CSS Modules, but this time I wanted to mix things up and bring back some old-school vibes 🥲 so I went with BEM throughout.

👀 Isolated Component Development with Storybook

So why is Storybook so valuable here? Because it lets you test each layer of your Atomic Design system individually, without any dependency on the running application.

Even before the app is up, you can validate Button, SearchBox, or ProductCard in complete isolation.

Step 1: Write a story for `Button`

// src/components/atoms/Button.stories.js
import Button from "./Button";

export default {
  title: "Atoms/Button",
  component: Button,
  args: {
    children: "Add to Cart",
    variant: "primary",
  },
};

export const Primary = {};

export const Secondary = {
  args: {
    children: "Details",
    variant: "secondary",
  },
};

Things to pay attention to:

title: "Atoms/Button" categorizes the component according to its atomic layer.
args makes it trivial to test different variations quickly.
Defining multiple visual states for the same atom becomes effortless.

Step 2: Write a story for `ProductCard`

// src/components/organisms/ProductCard.stories.js
import ProductCard from "./ProductCard";

export default {
  title: "Organisms/ProductCard",
  component: ProductCard,
  args: {
    product: {
      id: 1,
      emoji: "⌨️",
      title: "Mechanical Keyboard",
      description: "Hot-swappable, compact keyboard with RGB support.",
      price: 2499,
    },
  },
};

export const Default = {};

Key takeaways:

Organism-level components can also be tested independently of the page.
We can develop without waiting on a real API by using mock data.
Visual regression checks and UI reviews become much more manageable.

When Storybook and Atomic Design work together, producing, testing, and sharing components becomes significantly easier.

⚖️ Pros and Cons of Atomic Design

Like any solid approach, Atomic Design has both strengths and trade-offs. Rather than applying it blindly, it's worth understanding what it gives you and where it introduces overhead.

Pros

★ Component boundaries become much clearer.
★ Reusability increases significantly.
★ Storybook, testing, and design system workflows get stronger.
★ Large teams develop a shared UI vocabulary.
★ Refactoring becomes safer and more predictable.

Cons

★ Can feel over-engineered for small or single-screen apps.
★ Misinterpreting the layers leads to unnecessary file sprawl.
★ Over-decomposing every component can slow down initial development velocity.
★ Requires some upfront discipline, especially for teams new to the approach.

To be direct about it: Atomic Design is not a silver bullet. But for UI-heavy projects with real growth potential, it provides an exceptionally strong foundation.

😅 Common Mistakes

Here are the most frequent mistakes I see when teams adopt this approach:

★ Atomizing everything
A component isn't automatically an atom just because it's small. What matters is its responsibility.

★ Confusing templates and pages
Layout knowledge belongs in the template. Data and behavior belong in the page.

★ Embedding business logic in atoms
Atom-level components should stay as pure as possible.

★ Treating the folder structure as the end goal
Atomic Design exists for sustainable UI architecture, not for aesthetic folder organization.

★ Using Storybook purely as a showcase
The real value is in developing components in isolation and catching edge cases early.

Another critical mistake shows up in naming. The moment you see Card2, HeaderNew, or ButtonLatest, stop and reconsider.

🤔 When Should You Use It?

Atomic Design shines especially in projects where component count is growing and reusable UI pieces are multiplying. When combined with React, the approach feels even more natural because you're already working in a component-based world.

If you're building a small, single-screen app, you probably don't need this many layers. But if you're building a design system, if different teams are sharing the same UI pieces, or if the project is scaling quickly, Atomic Design becomes a very compelling choice.

Think of Atomic Design not just as theory, but as a daily development practice. When paired with React and Storybook, you end up with a frontend architecture that is more organized, more readable, and far more scalable.

📬 Feedback

While writing this article, I used GPT 5.4 High for research, source selection, and copyediting. Images were generated with Gemini 3 Pro Preview 2k (Nano Banana Pro).

I genuinely welcome feedback, suggestions, and criticism. If you'd like to get in touch, you can reach me via the social links on my website or connect with me on LinkedIn.

Best, Yasin 🤗

📚 References

Atomic Design by Brad Frost - Used to clarify the core concepts and layer definitions of the Atomic Design methodology.
React Documentation - Used for React component architecture, state management, and foundational patterns.
Storybook for React - Referenced for Storybook setup and React integration.
Vite Guide - Used to verify the Vite setup flow for bootstrapping the React project quickly.
Storybook Writing Stories - Used to clarify how story files should be structured and written.
BEM CSS Convention - The CSS methodology used throughout the article.

Monorepo Architecture with pnpm Workspace, Turborepo & Changesets 📦

Yasin ATEŞ — Wed, 01 Apr 2026 17:10:00 +0000

When you're developing a project with multiple packages, managing each one in its own repo can quickly turn into a nightmare. In this article, we'll set up a monorepo architecture from scratch using pnpm workspace, speed up build processes with Turborepo, and build an automated NPM publish pipeline with Changesets.

🏗️ What Is a Monorepo?

Let's say you're building a design system. You have a core package, a theme package, and a utils package. Now imagine keeping all of these in separate repositories.

When you fix a bug in the core package, what happens? You switch to the theme repo and update the dependency. Then you switch to the utils repo. You open separate PRs for each, wait for separate CI/CD pipelines, and publish separately. Even with just three packages, this process is exhausting — with ten, it's a total nightmare.

This is exactly where the monorepo comes in.

A monorepo is an architectural approach that houses multiple projects under a single repository. All your packages live in the same repo, share the same commit history, and can easily reference each other.

So why does this matter? Let's look at a few key advantages:

★ Code sharing in one place: Shared utilities, types, and configurations are instantly available to all packages. No need to wait for an NPM publish.

★ Atomic changes: You can make a change that affects multiple packages in a single commit. No more cross-repo PR synchronization headaches.

★ Consistent tooling: ESLint, Prettier, and TypeScript configurations are managed from a single source. The question "Why does this repo have different rules?" becomes a thing of the past.

★ Easy onboarding: When a new developer joins the project, a single git clone and pnpm install brings up the entire ecosystem.

🔧 Setting Up a pnpm Workspace

pnpm stands out among Node.js package managers for its monorepo support. Unlike npm and yarn, its content-addressable store keeps all dependencies in a global store and links them into your projects via hard links. This saves a massive amount of disk space.

Let's walk through setting up a monorepo architecture with pnpm workspace using a sample project.

Step 1: Install pnpm and Initialize the Project

Install pnpm globally:

npm install -g pnpm

Then initialize a new monorepo project:

mkdir my-design-system
cd my-design-system
pnpm init
git init

★ The pnpm init command creates a package.json file at the root level.

★ This file will serve as the main entry point for your monorepo. All workspace scripts will be managed from here.

Step 2: Create pnpm-workspace.yaml

Create a pnpm-workspace.yaml file in the project root:

packages:
  - "packages/*"
  - "apps/*"
  - "website"

★ The packages/* expression defines each folder under the packages directory as a separate workspace package.

★ apps/* includes applications, and website adds the documentation site to the workspace.

★ Without this file, pnpm won't recognize your project as a monorepo.

Step 3: Configure the Root package.json

Configure the root package.json for the monorepo:

{
  "name": "my-design-system",
  "private": true,
  "scripts": {
    "dev": "turbo run dev",
    "build": "turbo run build",
    "test": "turbo run test",
    "lint": "turbo run lint",
    "clean": "turbo run clean"
  },
  "devDependencies": {
    "turbo": "^2.3.1",
    "typescript": "^5.7.2",
    "tsup": "^8.3.5",
    "vitest": "^2.1.6",
    "prettier": "^3.4.1"
  },
  "packageManager": "pnpm@9.14.2",
  "engines": {
    "node": ">=18.0.0"
  }
}

★ "private": true is a critical setting. It prevents the root package from being accidentally published to NPM.

★ The "packageManager" field ensures that everyone who clones the project uses the same pnpm version. Corepack reads this field and automatically activates the correct package manager.

★ Shared devDependencies (like TypeScript and Prettier) are installed at the root, so individual packages don't need to install them separately.

Step 4: Create the Project Structure

Now let's create the folder structure:

mkdir -p packages/core
mkdir -p packages/utils
mkdir -p packages/theme
mkdir -p apps/docs

A typical monorepo structure looks like this:

my-design-system/
├── packages/
│   ├── core/               # Core library
│   ├── utils/              # Shared utility functions
│   └── theme/              # Theme and style definitions
├── apps/
│   └── docs/               # Documentation app
├── .changeset/             # Changesets configuration
├── .github/                # CI/CD workflows
├── package.json            # Root workspace config
├── pnpm-workspace.yaml     # Workspace definition
├── turbo.json              # Turborepo pipeline
├── tsconfig.base.json      # Shared TypeScript config
└── pnpm-lock.yaml          # Lock file

★ Libraries and shared modules live under packages/. Each one can be published as an independent npm package.

★ Applications that consume these packages go under apps/.

★ Configuration files at the root apply across the entire monorepo.

You also need to initialize each sub-package. For example, for packages/core:

cd packages/core
pnpm init

This creates a package.json for each package. Using namespaced package names is a good practice:

{
  "name": "@myds/core",
  "version": "0.1.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "tsup src/index.ts --format cjs,esm --dts",
    "dev": "tsup src/index.ts --format cjs,esm --dts --watch"
  }
}

★ Scoped names like @myds/core prevent namespace collisions on NPM.

★ The main and types fields ensure that other packages resolve the correct files when importing this package.

★ tsup is a great tool for quickly bundling TypeScript packages. It produces output in both CJS and ESM formats.

🔗 Cross-Package Dependency Management with the workspace Protocol

One of the most powerful features of a monorepo is the ability for packages to reference each other locally. pnpm achieves this through the workspace: protocol.

Let's make this concrete with an example. Say the @myds/theme package depends on @myds/core. You'd define this dependency like so:

{
  "name": "@myds/theme",
  "version": "0.4.0",
  "dependencies": {
    "@myds/core": "workspace:*"
  }
}

★ The workspace:* expression tells pnpm: "Don't download this package from the npm registry — use the local version from the workspace."
★ During development, packages are linked together via symlinks. Any change you make in core is instantly reflected in theme.

But what happens at publish time? Here's the beauty of pnpm: when you run pnpm publish, workspace:* is automatically converted to the actual version number.

So while package.json looks like this during development:

{
  "dependencies": {
    "@myds/core": "workspace:*"
  }
}

It becomes this when published to NPM:

{
  "dependencies": {
    "@myds/core": "0.4.0"
  }
}

Variants of the workspace Protocol

pnpm offers several workspace protocol variants:

★ workspace:* is the most commonly used variant. It means "use whatever version is currently in the workspace." At publish time, it resolves to an exact version (e.g., "0.4.0").

★ workspace:^ resolves to a caret range at publish time (e.g., "^0.4.0"). This allows minor and patch updates.

★ workspace:~ resolves to a tilde range at publish time (e.g., "~0.4.0"). This allows only patch updates.

Here's my take on when to use which: if you always publish all packages together, workspace:* is sufficient. But if you want consumers to be able to mix different versions, workspace:^ offers more flexibility.

Adding Dependencies Between Packages

To add one workspace package as a dependency of another, use the --filter flag:

pnpm add @myds/core --filter @myds/theme

★ The --filter flag runs the command only in the specified package.

★ pnpm automatically adds the dependency as workspace:^ (if it exists in the workspace).

You can also run scripts across all dependents of a specific package:

# Build @myds/core and all packages that depend on it
pnpm --filter "@myds/core..." build

To add a dependency to the root workspace, use the --workspace-root (or -w for short) flag:

pnpm add -D typescript --workspace-root

⚡ Build Orchestration with Turborepo

While pnpm workspace alone is sufficient for package management and linking, build processes get more complex as the number of packages grows. Questions like "Which package should be built first?" and "Do we really need to rebuild packages that haven't changed?" start to come up.

This is exactly where Turborepo steps in. Turborepo is a build system developed by Vercel that works directly with pnpm workspace. It reads pnpm's workspace structure, analyzes the dependency graph between packages, and optimizes tasks accordingly. It has two core features:

★ Smart task scheduling: It analyzes the dependency graph between packages and automatically determines the build order. Packages that don't depend on each other are run in parallel.

★ Hard caching: If a package hasn't changed, it restores the previous build output from cache. While the first build might take 30 seconds, a cached build can complete in 0.2 seconds.

Let's Set Up Turborepo

Add turbo to the root package.json:

pnpm add -D turbo --workspace-root

★ The --workspace-root flag (or -w for short) installs the package at the root workspace, making turbo available across the entire monorepo.

turbo.json Configuration

Create a turbo.json file at the project root:

{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": []
    },
    "test:watch": {
      "cache": false,
      "persistent": true
    },
    "lint": {
      "outputs": []
    },
    "clean": {
      "cache": false
    },
    "check-types": {
      "dependsOn": ["^build"],
      "outputs": []
    }
  }
}

Let's pause here and understand something important: the ^ in "dependsOn": ["^build"] is crucial. It means "run my dependencies' build task first, then build me." So before @myds/theme is built, its dependency @myds/core gets built first.

★ "outputs": ["dist/**"] tells Turborepo which files to cache. On the next build, if the source code hasn't changed, the dist/ folder is restored from cache.

★ "cache": false disables caching for certain tasks. Caching doesn't make sense for long-running (persistent) tasks like dev servers.

★ "persistent": true keeps the task running in the background. This is necessary for scenarios like dev servers and watch mode.

Now you can build all packages with a single command:

pnpm build
# This runs turbo run build
# Turborepo analyzes the dependency graph
# Builds in order: first core, then theme, then utils...
# Restores unchanged packages from cache

🦋 Version Management with Changesets

One of the trickiest aspects of a monorepo is version management. You have multiple packages, each potentially with its own independent version number. How do you decide which one to bump and when, or how to generate the changelog?

This is exactly where Changesets comes in. Changesets is a versioning tool that lets you record each change as a small markdown file.

Step 1: Install Changesets

pnpm add -D @changesets/cli --workspace-root
pnpm changeset init

★ The changeset init command creates a .changeset/ directory in your project.
★ Inside this directory, you'll find a config.json and a README.md file.

Step 2: Configure Changesets

Configure the .changeset/config.json file for your project:

{
  "$schema": "https://unpkg.com/@changesets/config@2.3.0/schema.json",
  "changelog": [
    "@changesets/changelog-github",
    { "repo": "your-org/your-monorepo" }
  ],
  "commit": false,
  "fixed": [],
  "linked": [["@myds/*"]],
  "access": "public",
  "baseBranch": "master",
  "updateInternalDependencies": "patch",
  "ignore": []
}

Let's break down each of these settings:

★ In the changelog section, we're using @changesets/changelog-github. This automatically adds PR links and contributor information to the changelog. Let's install this package as well:

pnpm add -D @changesets/changelog-github --workspace-root

★ The linked field is very important. [["@myds/*"]] tells Changesets that the versions of all packages under the @myds scope are linked together. If one gets a major bump, they all do.

★ "access": "public" ensures that scoped packages (like @myds/core) are published as public on NPM. Without this setting, scoped packages default to private and will throw an error during publish.

★ "updateInternalDependencies": "patch" automatically applies a patch bump to the internal dependency versions of packages that depend on an updated package.

★ "baseBranch": "master" determines which branch Changesets uses as its baseline. Depending on your project, this could be main or master.

Step 3: Create a Changeset

When you make a change, create a changeset file before opening a PR:

pnpm changeset

This launches an interactive wizard:

🦋  Which packages would you like to include?
  ◯ @myds/core
  ◯ @myds/theme
  ◯ @myds/utils

🦋  Which packages should have a major bump?
🦋  Which packages should have a minor bump?

🦋  Summary: Added dark mode support to the core package

This wizard creates a randomly named markdown file in the .changeset/ directory:

---
"@myds/core": minor
"@myds/theme": patch
---

Added dark mode support to the core package. Updated related color variables in the theme package.

★ The frontmatter section specifies which package gets bumped at which level.
★ The text below becomes the description added to the changelog.
★ This file is included in the commit and submitted for review along with the PR.

Step 4: Apply the Versions

Once all changesets have been collected, apply the versions:

pnpm changeset version

★ This command reads all changeset files.
★ Updates the version numbers in the relevant packages' package.json files.
★ Automatically creates/updates each package's CHANGELOG.md.
★ Deletes the consumed changeset files.

Step 5: Publish

After versions have been applied, publish:

pnpm changeset publish

This publishes all changed packages to the NPM registry. But are you going to do this manually every time? Of course not! In the next section, we'll automate this entire process 😁

🚀 Automated NPM Publishing with GitHub Actions

Enough theory — time to get our hands dirty! 🛠️ The real power of Changesets shines when combined with GitHub Actions. Let's build a CI/CD pipeline step by step.

Step 1: Create an NPM Token

First, you need to create an Automation Token on NPM:

★ Go to your profile settings on npmjs.com.

★ In the Access Tokens section, select Generate New Token.

★ Set the token type to Automation. This type allows publishing without requiring 2FA.

★ Copy the generated token (it's only shown once!).

Step 2: Add Tokens to GitHub Secrets

In your GitHub repo, go to Settings > Secrets and variables > Actions and add the following secret:

★ NPM_TOKEN: The NPM automation token you just created.

GITHUB_TOKEN is automatically provided by GitHub for every workflow run, so you don't need to set it up manually.

Step 3: Configure Repository Permissions

In your GitHub repo, go to Settings > Actions > General:

★ Under Workflow permissions, enable the "Read and write permissions" option.

★ Check the "Allow GitHub Actions to create and approve pull requests" checkbox.

Without these settings, the Changesets bot won't be able to create PRs.

Step 4: Create the Release Workflow File

Now create the .github/workflows/release.yml file:

name: Release

on:
  push:
    branches:
      - master

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: false

permissions:
  contents: write
  pull-requests: write
  packages: write
  id-token: write

jobs:
  release:
    name: Release
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repo
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup pnpm
        uses: pnpm/action-setup@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "pnpm"
          registry-url: "https://registry.npmjs.org"

      - name: Install Dependencies
        run: pnpm install --frozen-lockfile

      - name: Build All Packages
        run: pnpm build

      - name: Create Release Pull Request or Publish
        id: changesets
        uses: changesets/action@v1
        with:
          commit: "chore: update versions"
          title: "chore: update versions"
          publish: pnpm run ci:publish
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

There's a lot going on in this workflow. Let's break it down piece by piece:

★ The concurrency setting prevents multiple release workflows from running simultaneously. If a new push comes in while a publish is in progress, the old workflow isn't cancelled — instead, the new one waits in the queue.

★ The permissions block gives the workflow the authority to write to the repo, create PRs, and publish packages.

★ fetch-depth: 0 pulls the full git history. Changesets needs the commit history to calculate versions.

★ pnpm/action-setup@v4 installs pnpm in the CI environment. It reads the packageManager field from package.json to install the correct version.

★ --frozen-lockfile is a critical flag for CI. It installs the exact same dependencies as specified in the lock file. If pnpm-lock.yaml is out of date, it throws an error.

★ changesets/action@v1 is the action that does all the heavy lifting. It handles two different scenarios:

Scenario A: If there are pending changeset files in the .changeset/ directory, it creates or updates a "Version Packages" PR. This PR contains the version bumps and changelog updates.

Scenario B: If there are no pending changesets (i.e., after the Version Packages PR has been merged), it runs the publish command to publish the packages to NPM.

Step 5: Define the ci:publish Script

Add the publish script to the root package.json:

{
  "scripts": {
    "ci:publish": "pnpm publish -r --access public"
  }
}

★ The -r flag (recursive) publishes all workspace packages.
★ --access public ensures that scoped packages are published as public.

Changeset Bot

Optionally, you can install the Changeset Bot from github.com/apps/changeset-bot on your repo. This bot checks whether PRs include a changeset file and leaves a warning comment if they don't.

🎯 Demo: The Tuvix.js Monorepo Project

If you'd like to see the entire architecture described in this article in action, check out the Tuvix.js project I've been developing. Tuvix.js is a lightweight micro frontend framework that uses exactly the stack covered in this article:

★ pnpm workspace managing 14+ packages in a single repo

★ Turborepo for build orchestration and caching

★ Changesets for version management and automated NPM publishing

★ GitHub Actions for the CI/CD pipeline

You can explore the pnpm-workspace.yaml, turbo.json, .changeset/config.json, and GitHub Actions workflow files directly in the repository.

Check out the repo here 👇

github.com/yasinatesim/tuvix.js

📬 Feedback

While writing this article, I used my own notes for identifying sources and research, the Claude Opus 4.6 model for proofreading and additional research, and the Gemini 3 Pro Preview 2k (Nano Banana Pro) model for generating images.

I welcome any advice, suggestions, or feedback on this article. If you'd like to get in touch, you can reach me through my social media links on my website or via LinkedIn.

Best, Yasin 🤗

📚 Resources Used While Writing This Article

pnpm Workspaces — Official documentation for pnpm's workspace feature
Using Changesets with pnpm — Guide on Changesets integration with pnpm
Turborepo - Structuring a Repository — Turborepo's monorepo structuring documentation
Changesets GitHub Action — Official Changesets GitHub Action repository and usage guide
Tuvix.js GitHub Repository — My micro frontend framework, this is monorepo project referenced in this article

From Zero to Advanced: The Git Version Control System ☕️

Yasin ATEŞ — Tue, 17 Mar 2026 19:15:00 +0000

What is Git? 🤔

Git is a distributed version control system used to track changes in files over time during software development.

A Brief History of Git 📖

Git was developed by Linus Torvalds, the creator of Linux, in 2005.

The Linux project had been using BitKeeper, a proprietary version control system, under a free license since 2002. In 2005, BitKeeper's company alleged that Linux developer Andrew Tridgell had reverse-engineered their protocol, and subsequently revoked the project's free license. Linus Torvalds then decided to write his own version control system, and Git was born.

Why Version Control? 🧐

When working alone, manual backups may be enough. However, when multiple people work on the same project, tracking who changed what and when becomes difficult. A version control system automates this process and solves the following problems:

Maintains different versions of files
Enables multiple developers to work on the same codebase concurrently
Makes it easy to revert to a previous version when something goes wrong
Provides a complete audit trail of changes

How Does Git Work? ⚙️

Git consists of three fundamental layers:

Working Directory: The local directory where your files reside and where you actively work.
Staging Area: An intermediate area where changes are staged before being committed to the repository. Think of it as a preparation area for the next commit.
Repository (Repo): The repository where committed changes are stored. It is the .git folder in your project directory.

The basic workflow is:

You make changes in the working directory
You add those changes to the staging area with git add
You create a commit from the staged changes with git commit

Installation 💻

You can download and install the appropriate version for your operating system from git-scm.com.

To verify the installation, run the following command in your terminal:

git --version

Configuration (git config) 🔧

Before using Git, you should configure your user information. This information is recorded with every commit.

★ Global Configuration

The default configuration that applies to all Git repositories on your machine is defined as follows:

git config --global user.name "Yasin"
git config --global user.email "yasinatesim@gmail.com"

★ Local Configuration

The configuration that applies only to the current repository. If a global setting with the same name exists, the local setting overrides it:

git config --local user.name "Beril"
git config --local user.email "beril@yasinates.com"

💡 In this example, Git uses "Yasin" by default for all repositories on this machine, but in one specific project, the local configuration overrides the global one, and Git uses "Beril" for that repository.

★ Useful Additional Settings

# Set default branch name to main
git config --global init.defaultBranch main

# Set VS Code as the default editor
git config --global core.editor "code --wait"

# Enable colored output
git config --global color.ui auto

# Use rebase by default during pull
git config --global pull.rebase true

★ Git Alias (Shortcuts)

You can define shortcuts for frequently used commands:

git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.cm "commit -m"
git config --global alias.lg "log --oneline --graph --decorate --all"

Now you can type git st instead of git status, and git co instead of git checkout.

★ Checking Configurations

To check all configurations:

git config --list

Creating a Repository (git init) 📂

To turn your working directory into a Git repository, navigate to the target directory in the terminal and run:

git init

This command creates a hidden folder named .git in your directory. All of Git's data (commit history, branch information, configuration, etc.) is stored in this folder. The default branch name will be either master or main, depending on your Git version and configuration. Nowadays, platforms like GitHub default to main. You may also see the branch name displayed in your terminal prompt (for example, (main)), depending on your shell configuration.

💡 The concept of branches is covered in more detail later in this article.

Tracking File Status (git status) 🔍

To see the current status of the repository:

git status

This command shows which files have changed, which files are in the staging area, and which files are not yet tracked by Git (untracked).

Right after git init, it will report that there are no commits yet and suggest using git add. Think of git status as your compass in Git — when in doubt, run it.

Adding Changes to the Staging Area (git add) ➕

Let's start by creating a file. Create a file named names.txt in your working directory:

Eda
Beyza
Tuvana
Melis

When you run git status, Git will show this file as untracked. To add this file to the staging area, in other words, to tell Git to track it:

Add a single file:

git add names.txt

Add all changes at once:

git add .

⚠️ While git add . is practical, it can accidentally add irrelevant files to the staging area. Especially in large projects, it's a good habit to check git status first.

Reviewing Staging Area Changes 👀

Run git status again after the git add command:

git status

You will now see your file listed under "Changes to be committed." Git automatically classifies the type of changes in the staging area.

★ Change Types

New File (new file): A newly added file that was not previously tracked by Git.

Changes to be committed:
    new file:   names.txt

Modified File (modified): A file previously tracked by Git whose content has changed.

Changes not staged for commit:
    modified:   names.txt

To discard the modification:

git restore names.txt

Deleted File (deleted): A file tracked by Git that has been deleted.

Changes not staged for commit:
    deleted:    names.txt

To restore the deleted file:

git restore names.txt

★ Removing from the Staging Area

To remove a file that was accidentally added to the staging area (unstage it):

git restore --staged names.txt

💡 In older resources, you may see git reset HEAD <file> for unstaging. In modern Git, git restore --staged is recommended instead.

If you want Git to completely stop tracking a file (the file is not deleted from disk, but Git no longer tracks it):

git rm --cached names.txt

This command is especially useful for removing files from version control after they have been added to .gitignore.

★ More About the "git add" Command

Partial staging (-p): Shows changes in the file hunk by hunk and asks which ones you want to add:

git add -p

This command offers options for each change block:

y — Add this block
n — Do not add this block
s — Split the block into smaller pieces
q — Quit

This allows you to add only part of the changes in a file to the staging area.

📌 For all parameters of the git add command: git-scm.com/docs/git-add

Committing Changes (git commit) 📸

To create a commit from the staged changes:

git commit

Running this command without parameters opens the default text editor (usually Vim) and prompts you to enter a commit message. To exit Vim, type :wq and press Enter.

★ "git commit" Command Parameters

-m parameter — Lets you write the commit message directly in the terminal:

git commit -m "Names file created"

-a parameter — Commits only modified tracked files directly, without using git add. ⚠️ It does not add new (untracked) files:

git commit -am "Names edited"

--amend parameter — Edits the most recent commit message or updates the most recent commit with additional changes:

git commit --amend -m "Corrected commit message"

⚠️ --amend changes the commit hash. If you amend commits that have already been pushed, a force push is required. Use this carefully on shared branches.

📌 For all parameters of the git commit command: git-scm.com/docs/git-commit

★ How to Write a Good Commit Message?

💡 This is one of the most important sections of the article. One of the most common mistakes in Git is writing poor commit messages. A well-written commit message makes the project's history easier to read and makes collaboration much easier.

What makes a good commit message?

Short and descriptive (under 50 characters is ideal)
Describes what changed
Use imperative verbs such as: "fix", "add", "update"

Example:

❌ Bad: changes
✅ Good: Fix validation error in user login form

💡 In large projects, teams, or open source projects, linters are often used to standardize commit messages.

★ Commit Message Standards (Conventional Commits)

In larger projects, commit messages are often written according to a standard format. These standards:

Make commit history easier to read
Enable automatic changelog generation
Can integrate with CI/CD processes
Are compatible with semantic versioning

The Conventional Commits standard is widely used for this purpose.

★ Commit Format

feat(auth): add user login system
fix(player): fix audio dropout issue
docs(readme): update installation steps

feat — A new feature
fix — A bug fix
docs — Documentation changes
style — Code format changes (lint, whitespace, etc.)
refactor — Refactoring that does not change behavior
test — Tests added or updated
chore — Build, config, or utility tasks
ci — CI/CD pipeline changes
perf — Performance improvements
build — Build system or dependency changes

To automatically check this standard:

commitlint → lints commit messages
Commitizen → provides interactive help when writing commits

💡 Every commit must be reachable from a branch, tag, or HEAD reference. Commits that are no longer referenced are eventually cleaned up by Git's garbage collection mechanism after a certain amount of time (often around 90 days by default). Garbage collection is covered later in this article.

Viewing Commit History (git log) 📜

To view the commit history:

git log

Example output:

commit a1b2c3d4e5f6 (HEAD -> main)
Author: Rabia Kaya <rabia@example.com>
Date:   Mon Jun 9 2025

    Names file created

★ Frequently Used Parameters

git log --oneline                        # Each commit shown on a single line
git log --graph                          # Branch structure drawn as ASCII art
git log --oneline --graph --decorate --all  # Visual history with branch/tag pointers
git log -n 5                             # Only the last 5 commits
git log --author="Rabia"                 # Commits by a specific author
git log -- names.txt                     # History of a specific file
git log --follow -- names.txt            # Tracks history even if the file was renamed
git log --since="2025-01-01"             # Commits after a specific date

The commit hashes shown in git log output (for example, a1b2c3d) can be used with commands such as git checkout, git reset, and git revert to reference specific commits.

📌 For all parameters of the git log command: git-scm.com/docs/git-log

Viewing Differences (git diff) 🔎

To inspect line-by-line changes:

git diff

This command shows the differences between changes in the working directory and the staging area.

★ Different Comparison Scenarios

git diff                         # Working directory vs staging area
git diff --staged                # Staging area vs last commit
git diff --cached                # Equivalent to --staged
git diff HEAD                    # Working directory vs last commit
git diff <commit1> <commit2>     # Differences between two commits
git diff main..new-feature       # Differences between two branches
git diff -- names.txt            # Differences for a specific file only

Reading the output:

- Tuvana       # Deleted line (red)
+ Beril        # Added line (green)

📌 For all parameters of the git diff command: git-scm.com/docs/git-diff

File Deletion and Moving (git rm & git mv) 🗑️

★ git rm

To delete a file tracked by Git from both your filesystem and Git’s index:

git rm names.txt
git commit -m "names.txt deleted"

To remove a file from version control only, without deleting it from disk:

git rm --cached names.txt

★ git mv

To move or rename a file:

git mv old-name.txt new-name.txt
git commit -m "File renamed"

💡 Git actually detects file renames through content similarity. git mv does the same thing as deleting the file and adding it again with a new name behind the scenes, but using a single command is more convenient.

Branching (git branch) 🌿

Branches allow you to create independent workspaces within the same project. A branch is an independent line of development created from the current state of another branch. This lets you develop features or fix bugs without affecting the main codebase.

Historically, Git initialized repositories with master as the default branch name. Today, many teams and platforms use main instead. In this article, the examples use main.

★ Listing Branches

git branch              # Lists local branches
git branch -a           # Lists all, including remote-tracking branches

💡 References such as remotes/origin/main in git branch -a output are not the remote branch itself, but local tracking references updated after the last fetch or pull.

★ Creating a Branch

git branch new-names

After running this command, if you run git branch again, you will see that the new-names branch has been created. However, you are still on the main branch; see the next section for switching branches.

★ Deleting a Branch

git branch -d new-names     # Deletes a merged branch
git branch -D new-names     # Force-deletes it (even if not merged)

★ Renaming a Branch

git branch -m old-name new-name

Switching Between Branches and Commits (git checkout / git switch) 🔄

In Git version 2.23, the two different responsibilities of git checkout (branch switching and file restoration) were separated. git switch is recommended for switching branches, and git restore is recommended for restoring files. However, git checkout still works for both.

★ Switching Between Branches

git checkout new-names

or in Git 2.23+:

git switch new-names

Shortcut — Create and Switch:

To create a new branch and switch to it without running git branch separately:

git checkout -b new-names
# or
git switch -c new-names

★ Switching to a Commit

You can return to the state of any commit using its hash from the git log output:

git checkout a1b2c3d

⚠️ This places you in a detached HEAD state. In this state, commits you make are not attached to any branch, and they can become difficult to recover later if you switch away without creating a branch. If you want to preserve your changes, create a new branch:

git checkout -b rescue-branch

💡 The HEAD and detached HEAD concepts are explained in more detail later in this article.

★ Getting a File from a Specific Commit or Branch

To bring a file's state from a specific commit or branch into your working directory:

# Get the file state from a specific commit
git checkout a1b2c3d -- names.txt

# Get the file state from another branch
git checkout main -- names.txt

This command copies the file into your working directory and staging area. You do not leave your current branch.

💡 In older resources, you may see git checkout -- <file> for file restoration. In modern usage, git restore is recommended instead.

Merging Branches (git merge) 🤝

The git merge command is used to merge changes from one branch into another.

Example scenario:

# Create a new branch and switch to it
git checkout -b new-names

# Add "Rabia" to names.txt and commit the change
git add .
git commit -m "Rabia added"

# Switch back to main branch
git checkout main

# Merge new-names branch into main
git merge new-names

★ Merge Types

Fast-Forward Merge: If there are no new commits on the target branch (main), Git simply moves the branch pointer forward. No new merge commit is created:

main:    A → B → C
                  ↑ (fast-forward)
feature:          C → D → E

To prevent a fast-forward merge and always create a merge commit:

git merge --no-ff new-names

Three-Way Merge: When both branches have new commits, Git finds a common ancestor, performs a three-way comparison, and creates a new merge commit.

💡 To keep your feature branch up to date, you can regularly integrate changes from the main branch. This can be done with either merge or rebase:

git checkout new-names
git merge main
# or
git rebase main

Conflicts (Git Conflicts) ⚡

When the same lines of the same file are modified differently in two branches, a conflict occurs.

Example scenario:

Your names.txt file on the main branch looks like this:

Eda
Beyza
Tuvana
Melis

1. Create a new branch and change Tuvana on line 3 to Beril:

git checkout -b conflict-example
# names.txt → Change the line "Tuvana" to "Beril"
git commit -am "Tuvana replaced with Beril"

2. Switch back to main and change the same line to a different name:

git checkout main
# names.txt → Change the line "Tuvana" to "Rabia"
git commit -am "Tuvana replaced with Rabia"

3. Try to merge:

git checkout conflict-example
git merge main

Git shows the following conflict message:

CONFLICT (content): Merge conflict in names.txt
Automatic merge failed; fix conflicts and then commit the result.

When you open the file, Git marks the conflicting sections:

Eda
Beyza
<<<<<<< HEAD
Beril
=======
Rabia
>>>>>>> main
Melis

Between <<<<<<< HEAD and =======: Changes from your branch
Between ======= and >>>>>>> main: Changes from the branch being merged

To resolve the conflict:

Edit the file and keep the content you want
Remove the <<<<<<<, =======, >>>>>>> markers
Save and commit:

git add names.txt
git commit -m "Conflict resolved, updated as Beril"

★ Quick Fix: Ours or Theirs

If you want to directly choose one side in a conflict:

# Accept your branch's changes
git checkout --ours names.txt

# Accept the incoming changes
git checkout --theirs names.txt

git add names.txt
git commit -m "Conflict resolved"

★ Aborting the Merge (--abort)

To completely cancel the merge before resolving any conflicts:

git merge --abort

This command cancels the merge and restores your files to their pre-merge state.

★ Continuing the Merge (--continue)

After resolving the conflicts in the file and adding them to the staging area with git add:

git merge --continue

This is similar to running git commit, but it explicitly resumes the in-progress merge.

💡 Editors like VS Code automatically detect conflict markers and simplify resolution with buttons like "Accept Current", "Accept Incoming", and "Accept Both". Alternatively, you can use external tools configured with the git mergetool command. Many IDEs (WebStorm, PhpStorm, PyCharm, etc.) also provide their own merge editors to make conflict resolution easier.

Rebasing Commits onto Another Branch (git rebase) 🔀

Rebase creates a linear history by re-applying a branch's commits onto the tip of another branch.

git checkout new-feature
git rebase main

This command does the following:

Temporarily rewinds the new-feature branch
Takes the latest commits from the main branch
Re-applies new-feature's commits one by one on top of main's latest commit

★ Interactive Rebase

To edit, combine, reorder, or delete recent commits:

git rebase -i HEAD~3

In the editor that opens, you can change the command at the beginning of each commit:

pick a1b2c3d Names added
pick d4e5f6g New names edited
pick h7i8j9k Beyza added

Available commands:

pick — Keep the commit as is
reword — Change the commit message
squash — Combine with the previous commit (merges messages)
fixup — Combine with the previous commit (discards this commit's message)
drop — Completely remove the commit
edit — Stop to edit the commit

★ Rebase --onto

To detach a branch from its source branch and move it onto another branch:

git rebase --onto main feature bugfix
# Detach bugfix branch from feature and place it onto main

★ Rebase vs Merge

Merge

Merges branches and creates a merge commit
Does not rewrite commit history (safe)
If there is a conflict, it is resolved all at once

Rebase

Re-applies commits onto another branch's tip
Creates a cleaner history
Rewrites commit hashes
If conflicts occur, they are resolved for each commit separately
Typically used on personal branches

⚠️ This can cause problems on shared branches. Avoid rebasing branches that other people are already using.

If a conflict occurs during rebase:

# Resolve the conflict in the file, then:
git add .
git rebase --continue

# or abort the rebase entirely:
git rebase --abort

The HEAD Concept 🎯

HEAD is the answer to the question "where are you right now?" in Git. It points to the commit you are currently working on.

Normally, HEAD points to a branch and corresponds to that branch's latest commit:

cat .git/HEAD
# Output: ref: refs/heads/main

This means "HEAD → main → latest commit." When you make a new commit, HEAD moves forward to the new commit automatically.

★ Detached HEAD

When you switch directly to a commit with git checkout <commit-hash>, HEAD no longer points to a branch, but directly to that commit:

git checkout a1b2c3d

In this state, since any commits you make are not attached to a branch, they can become difficult to recover later when you switch to another branch. If you want to preserve your changes:

git checkout -b new-branch-name

💡 Commits made in detached HEAD do not disappear immediately. You can find their hashes with git reflog and recover them. However, after the reflog retention period expires (90 days by default), they may be cleaned up by garbage collection.

Tagging (git tag) 🏷️

Tags are used to add permanent labels (bookmarks) to specific commits. They are typically used to mark version numbers. Unlike branches, tags are fixed and do not move.

★ Lightweight Tag

A simple pointer that stores no additional information:

git tag v1.0

★ Annotated Tag

A tag that includes author, date, and message information. Recommended for version tags:

git tag -a v1.0 -m "First stable release"

★ Adding a Tag to a Specific Commit

git tag -a v0.9 a1b2c3d -m "Beta release"

★ Tag Operations

git tag                    # List all tags
git show v1.0              # Show tag details
git tag -d v1.0            # Delete local tag
git push origin v1.0       # Push tag to remote repository
git push origin --tags     # Push all tags

Undoing Changes ↩️

Use git restore to discard changes in the working directory or unstage files from the index:

# Restore the file to its last committed state (working directory changes are lost)
git restore names.txt

# Remove the file from the staging area, but keep the file unchanged
git restore --staged names.txt

★ git reset

Used to undo commit history. git reset moves the current branch reference backward to an earlier commit; depending on the mode used, the staging area and working directory are adjusted accordingly.

It has three modes:

--soft: The commit is undone, but the changes remain in the staging area. Useful when you want to correct the commit message or adjust the contents of the commit:

git reset --soft HEAD~1

--mixed (default): The commit is undone, the changes remain in the working directory, but they are removed from the staging area:

git reset HEAD~1
# or
git reset --mixed HEAD~1

--hard: The commit and all changes are completely deleted:

git reset --hard HEAD~1

⚠️ The --hard parameter permanently deletes changes. Be careful.

Commits removed by git reset --hard can often still be recovered with git reflog, as long as they have not been pruned by garbage collection. By default, unreachable commits are typically recoverable for some time (often around 90 days, depending on reflog and GC settings). Good commit messages also make lost commits much easier to identify in the reflog. If your commit messages are all the same, finding the right one becomes much harder 🥲

HEAD~1 means the previous commit. HEAD~3 means three commits back. You can also use a specific commit hash:

git reset --soft a1b2c3d

★ git revert

Creates a new commit that undoes the changes introduced by a specific commit. It does not erase history, so it can be used safely on shared branches:

git revert a1b2c3d

Reverting a merge commit:

When reverting merge commits, you need to specify which parent to use as the base with the -m parameter:

git revert -m 1 <merge-commit-hash>

★ Which one should you use?

File changes you have not committed yet → git restore
Commits you have not pushed yet → git reset
Safely undo pushed commits → git revert

Reference History (git reflog) 🕵️

git reflog is a safety net that records updates to HEAD and other references locally. Even after running a dangerous command like git reset --hard, you can often find lost commits here:

git reflog

Example output:

a1b2c3d HEAD@{0}: reset: moving to HEAD~1
f4e5d6c HEAD@{1}: commit: Beril added
b7a8c9d HEAD@{2}: commit: Names file created

You can find the hash of the lost commit and go back to it:

git reset --hard f4e5d6c

💡 Reflog entries are kept for 90 days by default.

Stashing Changes (git stash) 📦

Used to temporarily save changes you are working on without committing them. This is very useful when an urgent task comes up and you need to switch branches.

★ Basic Commands

git stash                              # Stash changes
git stash push -m "Description"        # Stash with a message
git stash -u                           # Include untracked files
git stash --all                        # Stash everything, including ignored files
git stash list                         # List stashes
git stash show                         # Show a summary of the latest stash
git stash show -p                      # Show the detailed diff of the latest stash

💡 In older resources, you may see git stash save "Description". In modern Git, git stash push -m "Description" is recommended instead.

⚠️ The default git stash command does not include untracked files. To save those as well, use the -u parameter.

★ Restoring

git stash pop                    # Apply the latest stash and remove it from the stash list
git stash apply                  # Apply the latest stash and keep it in the stash list
git stash apply stash@{2}        # Apply a specific stash

★ Cleanup

git stash drop                   # Drop the latest stash
git stash drop stash@{1}         # Drop a specific stash
git stash clear                  # Clear all stashes

★ Example Scenario

You are adding new names to names.txt. Suddenly, an urgent fix is needed:

# Stash the work in progress
git stash push -m "I was updating Tuvana's information"

# Switch to main and make the fix
git checkout main
git commit -am "Urgent fix applied"

# Switch back to your feature branch and pick up where you left off
git checkout new-feature
git stash pop

Ignoring Files (.gitignore) 🙈

Create a .gitignore file in the project root directory to prevent Git from tracking certain files and folders:

# Dependency folders
node_modules/
vendor/

# Build outputs
dist/
build/
*.class

# Environment variables (passwords, API keys, etc.)
.env
.env.local

# IDE files
.idea/
.vscode/
*.swp

# Operating system files
.DS_Store
Thumbs.db

# Log files
*.log

# Compiled files
*.o
*.exe

★ Important Notes

Files that were already being tracked by Git before the .gitignore file was created will not automatically stop being tracked when added to .gitignore. To remove these files from tracking:

git rm --cached filename.txt

Empty folders are not tracked by Git. If you want to keep an otherwise empty directory in the repository, you can place an empty file named .gitkeep inside it. .gitkeep is not a Git-specific feature; it is a community convention. The file name can be anything, but .gitkeep is commonly used.

★ Global .gitignore

You can define a global .gitignore file that applies to all your projects. This is useful for system-specific files like .DS_Store, Thumbs.db, and temporary editor files:

git config --global core.excludesfile ~/.gitignore_global

Then add your global rules to the ~/.gitignore_global file.

📌 Ready-made .gitignore templates for different project types: github.com/github/gitignore

Remote Repository (Remote) 🌐

So far, all operations have been local. To host the project on platforms such as GitHub, GitLab, or Bitbucket and share it with others, you use a remote repository.

★ HTTPS vs SSH

There are two common ways to connect to a remote repository:

# HTTPS — Authentication with username/password or token
git remote add origin https://github.com/user/project.git

# SSH — Authentication with SSH key (more practical)
git remote add origin git@github.com:user/project.git

💡 To use SSH, you first need to create an SSH key and add it to your platform (GitHub, GitLab, etc.). For detailed steps: docs.github.com/en/authentication/connecting-to-github-with-ssh

★ Adding a Remote Repository

git remote add origin https://github.com/user/project.git

Here, origin is the local alias for the remote repository. By convention, origin is commonly used, but you can choose any name you like.

★ Remote-Tracking Branch Concept

References like origin/main are local references that reflect the last fetched state of remote branches. This is not the live state of the remote server itself; it is a local reference updated after the last fetch or pull. This lets you inspect the last known state of the remote branch even while offline.

★ Listing Remote Repositories

git remote -v

Example output:

origin  https://github.com/user/project.git (fetch)
origin  https://github.com/user/project.git (push)

★ Changing a Remote Repository URL

git remote set-url origin https://github.com/user/new-project.git

★ Removing a Remote Repository

git remote remove origin

Cloning (git clone) 📥

To copy a remote repository to your local machine:

git clone https://github.com/user/project.git

This command:

Creates a folder with the project name
Creates the .git folder
Downloads the repository history and working tree
Automatically sets up the origin remote

★ Additional Parameters

# Clone a specific branch
git clone -b branch-name https://github.com/user/project.git

# Clone with a different folder name
git clone https://github.com/user/project.git my-project

# Clone only the last commit (for speed in large projects)
git clone --depth 1 https://github.com/user/project.git

Pulling Changes (git fetch & git pull) ⬇️

★ git fetch

Downloads changes from the remote repository but does not merge them into your local branch. This is useful when you want to review changes first:

git fetch origin

To review changes in the remote branch after fetching:

git diff main origin/main

If the changes look correct, merge them:

git merge origin/main

★ git pull

Performs fetch + merge with a single command. It downloads changes from the remote repository and merges them into your local branch:

git pull origin main

For a cleaner history, pull with rebase:

git pull --rebase origin main

💡 To make git pull --rebase the default behavior:

git config --global pull.rebase true

★ Pull vs Fetch

git fetch: Downloads changes but does not merge them. Safer because it gives you a chance to review changes first. Use it when you want to inspect changes before integrating them.
git pull: Downloads changes and automatically merges them. Conflicts may occur. Use it when you want to update quickly.

💡 git pull = git fetch + git merge

Pushing Changes (git push) ⬆️

To send your local commits to the remote repository:

git push origin main

★ Setting Upstream for First Push

The -u (upstream) parameter is used when pushing a new branch for the first time. This sets the upstream tracking relationship between the local branch and the remote branch. After that, simply running git push is enough for future pushes:

git push -u origin new-feature

To change or set the upstream of an existing branch:

git branch --set-upstream-to=origin/main main

★ Other Parameters

git push origin --delete branch-name    # Delete remote branch
git push --force                       # or -f  ⚠️ be extra careful when using
git push --force-with-lease            # Safer force push

⚠️ The --force parameter rewrites history on the remote repository. It can cause teammates to lose their work. If you use --force-with-lease instead, Git rejects the push if the remote branch contains commits you do not know about.

Fork and Pull Request 🍴

★ Fork

Copying someone else's repository into your own GitHub/GitLab account. This is done through the Fork button in the platform interface. A fork remains associated with the original repository on the hosting platform.

★ Pull Request (PR) / Merge Request (MR)

A request to have changes from your fork or branch accepted into the main repository. It is called a Pull Request on GitHub and a Merge Request on GitLab.

Typical workflow:

Fork the repository
Clone it to your local machine
Create a new branch
Make your changes and commit them
Push to your fork
Open a Pull Request on the platform
Code review is performed
If approved, it is merged into the main branch

Branching Strategies 🗺️

Common strategies for how teams use Git:

★ Git Flow

A comprehensive branching strategy, often used in long-lived projects:

main — Published stable version
develop — Development branch
feature/* — For new features
release/* — For release preparation
hotfix/* — For urgent fixes

★ GitHub Flow

Well suited to teams that deploy frequently:

main — Always in a deployable state
feature branch — New feature or fix
Pull Request — Code review and merging

★ Trunk-Based Development

Short-lived branches are used and continuously merged into the main branch (trunk). It is commonly used with continuous integration (CI) in large teams.

💡 The best strategy depends on team size, project type, and deployment frequency. For small teams, GitHub Flow is generally enough.

Cherry Picking (git cherry-pick) 🍒

To take only a specific commit from another branch instead of merging the entire branch:

git cherry-pick a1b2c3d

Example scenario:

The new-feature branch has 5 commits, but you only want to bring the bug fix from one of them into main:

git checkout main
git cherry-pick f4e5d6c

To take multiple commits:

git cherry-pick a1b2c3d f4e5d6c

If a conflict occurs during cherry-pick, resolve it like a normal merge conflict and continue:

git add .
git cherry-pick --continue

# or cancel:
git cherry-pick --abort

Line-by-Line History (git blame) 🔬

To see who last changed each line of a file and when:

git blame names.txt

Example output:

a1b2c3d4 (Beril Dumanlı     2025-01-10) Eda
f4e5d6c7 (Sitare Demir      2025-02-15) Beyza
b7a8c9d0 (Arya Çelik        2025-03-22) Tuvana
a1b2c3d4 (Beril Dumanlı     2025-01-10) Melis

💡 In the example above, the first and last lines were changed by the same person at different positions in the file. Lines 2 and 3 in between were changed by different people.

★ Additional Parameters

git blame -L 5,10 names.txt     # Only lines 5-10
git blame -e names.txt           # Show email addresses
git blame -w names.txt           # Ignore whitespace changes

Useful for tracing when and by whom a line was last modified.

Searching (git grep) 🔎

To search for text within the contents of files in the repository:

git grep "Beril"

Example output:

names.txt:Beril
notes.txt:Beril's note added

★ Additional Parameters

git grep -n "Beril"                  # Show line numbers
git grep -c "Beril"                  # Number of matches in each file
git grep -i "beril"                  # Case-insensitive search
git grep "Beril" -- "*.txt"          # Search only in .txt files
git grep "Beril" a1b2c3d             # Search in files at a specific commit

💡 Unlike regular grep, git grep searches only files tracked by Git. It skips files listed in .gitignore, so it does not waste time scanning directories like node_modules. This makes it much faster in large projects.

Finding Bugs with Binary Search (git bisect) 🐛

There is a bug in your project, but you do not know which commit introduced it. git bisect uses a binary search algorithm to quickly find the problematic commit among hundreds of commits.

★ Usage

# Start bisect
git bisect start

# Mark the current commit as buggy
git bisect bad

# Mark an old commit that you know was working
git bisect good a1b2c3d

Git automatically checks out a commit in the middle. Test the project:

# If the bug exists in this commit too:
git bisect bad

# If the bug does not exist in this commit:
git bisect good

At each step, Git cuts the search space in half. It finds the buggy commit in just a few steps:

f4e5d6c is the first bad commit

When you are done:

git bisect reset

💡 If there are 128 commits, git bisect finds the buggy commit in at most 7 steps. (log₂128 = 7)

Viewing Commit Details (git show) 🔍

To see the details of a single commit (author, date, message, and changes made):

git show               # Details of the last commit
git show a1b2c3d       # Details of a specific commit
git show v1.0          # Details of the commit the tag points to

While git log shows commit history, git show displays the full details of a single commit, including the diff.

Cleaning Untracked Files (git clean) 🧹

To delete untracked files from the working directory:

git clean -n           # Show what would be deleted first (dry run)
git clean -f           # Delete untracked files
git clean -fd          # Delete files and directories
git clean -fdx         # Delete everything including files in .gitignore

⚠️ git clean is irreversible. Always check with -n (dry run) before deleting.

Git Hooks 🪝

Hooks are scripts that run automatically on specific Git events. They are located in the .git/hooks/ folder.

★ Commonly Used Hooks

pre-commit — Runs before a commit (lint, format check)
commit-msg — Runs after the commit message is entered, before the commit is finalized (message format check)
pre-push — Runs before a push (for example, running tests)
post-merge — Runs after a merge (for example, updating dependencies)

★ Example: Lint Check Before Commit

Create a .git/hooks/pre-commit file and make it executable:

#!/bin/sh
npm run lint
if [ $? -ne 0 ]; then
  echo "Lint errors found. Commit cancelled."
  exit 1
fi

chmod +x .git/hooks/pre-commit

💡 Hooks in the .git/hooks/ folder are not shared with the repository. For team-wide hook sharing, tools like Husky can be used.

Managing External Repositories (Submodule & Subtree) 📦

In large projects, you may need to include other repositories in your own project.

★ git submodule

Embeds another repository inside your repository as a reference to a specific commit. The subproject remains independent; only a specific commit is referenced:

git submodule add https://github.com/user/library.git libs/library
git commit -m "Library added as submodule"

When a repository with submodules is cloned, submodule contents are not checked out automatically:

git clone --recurse-submodules <url>
# or after cloning:
git submodule update --init --recursive

★ git subtree

Copies another repository's code directly into your project. It is simpler than submodule, but it increases repository size:

git subtree add --prefix=libs/library https://github.com/user/library.git main --squash

💡 Submodule is more widely used, but managing it is more complex. Subtree is a simpler alternative. Choose based on your needs.

Git Garbage Collection (git gc) 🗑️

Over time, Git accumulates unreachable and unnecessary objects (commits, blobs, trees) in its internal structure. git gc cleans up these objects and optimizes the repository:

git gc

★ When Does It Run?

Git automatically triggers gc during some commands (git merge, git rebase, etc.)
You can also run it manually

★ What Gets Cleaned?

Orphan commits not referenced by any branch, tag, or HEAD
Reflog entries past their retention period (default 90 days)
Unused Git objects

git gc --aggressive       # Deeper optimization (slow but effective)
git gc --prune=now        # Delete all unreachable objects immediately

⚠️ Under normal circumstances, you do not need to run git gc manually. Git handles this automatically in the background.

📌 Detailed information: git-scm.com/docs/git-gc

Git Internals: A Brief Look 🧬

Let's take a brief look at what is inside Git's .git folder:

.git/
├── HEAD              # Reference to current branch
├── config            # Repository configuration
├── objects/          # All Git objects (commit, tree, blob)
├── refs/             # Branch and tag references
│   ├── heads/        # Local branches
│   └── tags/         # Tags
├── hooks/            # Automatically triggered scripts
└── index             # Staging area data

★ Git's Three Fundamental Objects

Blob — Stores file content (does not store the file name)
Tree — Stores the structure of a directory (which blob corresponds to which file name)
Commit — Represents a snapshot; contains tree, author, date, and message information

Git traditionally identifies each object with a SHA-1 hash. This hash is generated from the object's content. Newer versions also support SHA-256.

# To view an object's content:
git cat-file -p a1b2c3d

# To view an object's type:
git cat-file -t a1b2c3d

💡 Git internals is a large topic on its own. It will be covered in more detail in a separate article.

Git Commands Summary 📋

★ Basic Commands

git init — Creates a new repository
git clone <url> — Clones a remote repository
git status — Shows repository status
git add <file> — Adds a file to the staging area
git add . — Adds all changes
git commit -m "message" — Creates a commit
git commit -am "message" — Commits modified tracked files
git show <hash> — Shows commit details

★ File Operations

git rm <file> — Deletes a file and stages the removal
git rm --cached <file> — Removes a file from version control (does not delete it from disk)
git mv <old> <new> — Moves/renames a file
git clean -fd — Deletes untracked files and directories

★ History and Diffs

git log — Shows commit history
git log --oneline --graph --decorate --all — Visual commit history
git diff — Shows file differences
git blame <file> — Shows who changed each line
git reflog — Shows HEAD/reference update history
git shortlog -sn — Commit counts by contributor

★ Branching and Merging

git branch <name> — Creates a new branch
git branch -d <name> — Deletes a branch
git checkout <branch> — Switches to a branch
git checkout -b <name> — Creates a branch and switches to it
git switch <branch> — Switches to a branch (modern)
git merge <branch> — Merges branches
git merge --no-ff <branch> — Always creates a merge commit
git merge --abort — Cancels the merge
git rebase <branch> — Rebases commits
git rebase --onto <new-base> <old-base> <branch> — Moves a branch to a different base
git cherry-pick <hash> — Applies a specific commit

★ Undoing

git restore <file> — Discards file changes
git restore --staged <file> — Removes a file from staging
git reset --soft HEAD~1 — Undoes a commit, keeps changes staged
git reset --hard HEAD~1 — Completely deletes a commit and its changes
git revert <hash> — Creates a new commit that undoes another commit

★ Temporary Storage

git stash — Temporarily saves changes
git stash push -m "message" — Saves changes with a message
git stash -u — Saves changes including untracked files
git stash pop — Restores the latest stash
git stash list — Lists stashes

★ Remote Repository

git remote add <name> <url> — Adds a remote repository
git remote -v — Lists remote repositories
git fetch — Downloads remote changes
git pull — Downloads and merges changes
git pull --rebase — Downloads and rebases changes
git push — Pushes commits to a remote repository
git push -u origin <branch> — Pushes a branch for the first time
git push --force-with-lease — Safer force push

★ Tagging and Searching

git tag <name> — Adds a tag
git tag -a <name> -m "message" — Adds an annotated tag
git grep "text" — Searches file contents
git bisect start — Starts bug hunting with binary search

★ Configuration Shortcuts

git config --global alias.st status — git st shortcut
git config --global alias.co checkout — git co shortcut
git config --global alias.br branch — git br shortcut
git config --global alias.lg "log --oneline --graph --decorate --all" — git lg shortcut

📬 Feedback

While writing this article, I relied on my own notes for source selection and research, and used the "Claude Opus 4" model for proofreading and additional research. Images were generated using the "Gemini 3 Pro Preview 2k (Nano Banana Pro)" model.

I welcome feedback, suggestions, and constructive criticism on this article. If you'd like to get in touch, you can reach me through the social links on my website or via LinkedIn.

Best, Yasin 🤗

📚 Sources Used While Writing This Article

Keep Your GitHub Profile README Alive: Auto-Update with GitHub Actions ⚡

Yasin ATEŞ — Tue, 10 Mar 2026 03:00:00 +0000

Someone visiting your GitHub profile wants to get to know you. They want to see who you are, what you build, what you write. But most profile READMEs are written once and then left untouched for years. A "latest posts" list from 2021, expired projects, a tech stack still waiting to be updated.

What if your README updated itself every morning?

In this article we will build a system that automatically pulls your Medium and dev.to articles, runs daily via GitHub Actions, and keeps your README alive. We will walk through every step: the Python script, the workflow file, placeholder markers, and manual triggering.

1. How Does It Work? 🔄

The system we are building has four parts:

We place special HTML comment lines inside README.md (like ). The script finds the content between these markers and replaces it; it does not touch anything outside the markers.

The Python script calls Medium's RSS feed and dev.to's REST API, collects article titles and URLs, then updates the README.

The GitHub Actions workflow runs this script on a schedule. It triggers every day at 06:00 UTC; if the script makes any changes, it automatically commits and pushes.

The manual trigger option means you do not have to wait. The moment you publish a new article, you can run it with a single click from the Actions tab.

💡 The entire system runs on GitHub's own infrastructure. No external server, no paid service, and your machine does not need to be on. GitHub Actions is free for public repos.

2. What Is a GitHub Profile README? 👤

When you create a repository with the same name as your username, GitHub automatically displays the README.md inside it on your profile page. This is a special GitHub feature.

How to Create the Profile README Repo

Click the New repository button on GitHub
Enter your own username as the repository name (e.g. yasinatesim)
Make sure Public is selected
Check the Add a README file checkbox
Click Create repository

When the repo is created, GitHub greets you with "✨ yasinatesim/yasinatesim is a special repository." Everything you write in README.md starts appearing on your profile.

⚠️ The repository name must be exactly the same as your username, including case. Yasinatesim and yasinatesim are different repos and the profile feature will not work.

3. Adding Placeholder Markers to the README 📍

How does the script know what to update in the README? Through special markers we place as HTML comment lines. These markers are invisible in the browser and on GitHub, but they act as coordinates for the script.

Add the following block wherever you want articles to appear in your README:

## ✍️ Latest Medium Articles

<!-- MEDIUM-ARTICLES:START -->
<!-- MEDIUM-ARTICLES:END -->

## 📝 Latest dev.to Articles

<!-- DEVTO-ARTICLES:START -->
<!-- DEVTO-ARTICLES:END -->

When the script runs, it deletes everything between the two markers and writes the current article list in its place. It does not touch any line outside the markers. After the first run the output will look like this:

## ✍️ Latest Medium Articles

<!-- MEDIUM-ARTICLES:START -->
- [Micro Frontend Architecture (with React Examples)](https://medium.com/...)
- [How We Integrated Google Lighthouse into Our Dev Process](https://medium.com/...) *(Hepsiburadatech)*
- [TypeScript from A to Z](https://medium.com/...)
<!-- MEDIUM-ARTICLES:END -->

💡 The example above is from my own GitHub Profile README. Publication info (the channel name in parentheses) is extracted automatically from the article URL by the script. When it sees a URL like medium.com/publication/..., it grabs the slug and adds it in parentheses next to the article title (shown on the second line above). For personal profile articles (medium.com/@yasinatesim/...) it shows no parentheses.

4. Python Script: Fetching Article Data 🐍

The entire script uses two external libraries: feedparser (for the Medium RSS feed) and requests (for the dev.to API). No other dependencies.

scripts/
└── fetch_articles.py

4.1 Basic Structure

"""
fetch_articles.py
-----------------
Fetches all articles from Medium RSS and the dev.to API,
then automatically updates the placeholders in README.md.
"""

import re
import feedparser
import requests

MEDIUM_USERNAME = "your-username"   # without the @ sign
DEVTO_USERNAME  = "your-username"
README_PATH     = "README.md"

MEDIUM_START = "<!-- MEDIUM-ARTICLES:START -->"
MEDIUM_END   = "<!-- MEDIUM-ARTICLES:END -->"
DEVTO_START  = "<!-- DEVTO-ARTICLES:START -->"
DEVTO_END    = "<!-- DEVTO-ARTICLES:END -->"

4.2 Fetching Medium Articles

Medium provides a public RSS feed for every user. feedparser converts this XML feed into Python objects. We do not set a limit; we process the entire feed.entries list.

def fetch_medium_articles():
    url  = f"https://medium.com/feed/@{MEDIUM_USERNAME}"
    feed = feedparser.parse(url)
    articles = []

    for entry in feed.entries:
        publication = None
        link = entry.link

        # Extract publication info from the URL
        # medium.com/publication-slug/... → publication exists
        # medium.com/@username/...        → personal profile, no publication
        subdomain_match = re.match(r"https://([^.]+)\.medium\.com/", link)
        path_match      = re.match(r"https://medium\.com/([^@/][^/]*)/", link)

        if subdomain_match:
            slug = subdomain_match.group(1)
            publication = slug.replace("-", " ").title()
        elif path_match:
            slug = path_match.group(1)
            # Filter out system paths (tag, search, topic, etc.)
            system_paths = {"tag", "tags", "search", "topic", "topics",
                            "m", "about", "membership"}
            if slug not in system_paths:
                publication = slug.replace("-", " ").title()

        articles.append({
            "title":       entry.title,
            "url":         link,
            "publication": publication,
        })

    return articles

⚠️ Medium's RSS feed returns only the last 10 articles by default. This is a limit set by Medium; no matter what your script does, it cannot pull more than 10 via RSS. If you want to show all your articles, you will need to look into scraping approaches.

I do not yet have 10 published articles on Medium, so I have not integrated this into my own GitHub Profile README yet. 😁 I will update the repo once I cross 10 articles. The repo link is in the Demo section at the end.

4.3 Fetching dev.to Articles

dev.to has an open REST API that requires no API key. Since it supports pagination, we can pull all articles with a while loop:

def fetch_devto_articles():
    page, articles = 1, []

    while True:
        url = (
            f"https://dev.to/api/articles"
            f"?username={DEVTO_USERNAME}&per_page=100&page={page}"
        )
        response = requests.get(url, timeout=10)

        if response.status_code != 200:
            break

        batch = response.json()
        if not batch:          # Empty page → no more data
            break

        for item in batch:
            articles.append({
                "title": item["title"],
                "url":   item["url"],
            })

        page += 1

    return articles

4.4 Building Markdown Rows

def build_medium_rows(articles):
    if not articles:
        return "_No articles found._"

    rows = []
    for a in articles:
        # Show publication in italic parentheses if present
        pub = f" *({a['publication']})*" if a.get("publication") else ""
        rows.append(f'- [{a["title"]}]({a["url"]}){pub}')

    return "\n".join(rows)


def build_devto_rows(articles):
    if not articles:
        return "_No articles found._"

    return "\n".join(
        f'- [{a["title"]}]({a["url"]})' for a in articles
    )

4.5 Updating the README

We use regex to find the block between the markers and replace it with the new content. The re.DOTALL flag makes . match newlines as well; without it, multi-line blocks are not captured.

def replace_section(content, start_marker, end_marker, new_body):
    pattern = re.compile(
        rf"{re.escape(start_marker)}.*?{re.escape(end_marker)}",
        re.DOTALL,
    )
    replacement = f"{start_marker}\n{new_body}\n{end_marker}"
    return pattern.sub(replacement, content)


def main():
    print("📡 Fetching Medium articles...")
    medium_articles = fetch_medium_articles()
    print(f"   ✅ {len(medium_articles)} articles fetched.")

    print("📡 Fetching dev.to articles...")
    devto_articles = fetch_devto_articles()
    print(f"   ✅ {len(devto_articles)} articles fetched.")

    with open(README_PATH, "r", encoding="utf-8") as f:
        content = f.read()

    content = replace_section(
        content, MEDIUM_START, MEDIUM_END, build_medium_rows(medium_articles)
    )
    content = replace_section(
        content, DEVTO_START, DEVTO_END, build_devto_rows(devto_articles)
    )

    with open(README_PATH, "w", encoding="utf-8") as f:
        f.write(content)

    print("✅ README.md updated successfully!")


if __name__ == "__main__":
    main()

5. GitHub Actions Workflow File ⚙️

The workflow file goes inside the .github/workflows/ folder. GitHub automatically scans this folder and treats YAML files as workflows.

.github/
└── workflows/
    └── update-articles.yml

File contents:

name: 📝 Update Blog Articles

on:
  schedule:
    - cron: "0 6 * * *"   # Every day at 06:00 UTC
  workflow_dispatch:        # For manual triggering from the Actions tab

jobs:
  update-readme:
    name: Fetch & Update Articles
    runs-on: ubuntu-latest

    steps:
      - name: 🔄 Checkout Repository
        uses: actions/checkout@v4

      - name: 🐍 Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: 📦 Install Dependencies
        run: pip install requests feedparser

      - name: 🚀 Run Article Fetcher
        run: python scripts/fetch_articles.py

      - name: 💾 Commit & Push Changes
        run: |
          git config --local user.email "github-actions[bot]@users.noreply.github.com"
          git config --local user.name "github-actions[bot]"
          git add README.md
          git diff --staged --quiet || git commit -m "📝 Auto-update: Latest blog articles [$(date +'%Y-%m-%d')]"
          git push

actions/checkout@v4 -- Copies your repo to the virtual machine (ubuntu-latest) where the workflow runs. Without it the script cannot find README.md.

actions/setup-python@v5 -- Sets up the Python 3.11 environment. Even though GitHub Actions machines come with Python pre-installed, pinning the version is safer.

pip install requests feedparser -- Installs the two dependencies.

python scripts/fetch_articles.py -- Runs the script. This step updates README.md but does not commit yet.

Commit & Push step -- The critical line is:

git diff --staged --quiet || git commit -m "..."

git diff --staged --quiet returns a non-zero exit code when there are changes in the README; thanks to the || operator, a commit is made only if there are changes, and nothing happens otherwise. Without this, an empty commit would be created on every run.

💡 Cron syntax: 0 6 * * * means minute=0, hour=6, every day, every month, every day of the week. Keep in mind it uses UTC. For a different time, use crontab.guru.

6. Manual Triggering 🖱️

The cron job runs every morning, but you might not want to wait after publishing a new article. The workflow_dispatch trigger lets you run it whenever you want:

Go to your repository on GitHub
Click the Actions tab at the top
Click 📝 Update Blog Articles in the left menu
Click the Run workflow button that appears on the right
Click Run workflow again in the dropdown that opens

The workflow starts within a few seconds. A yellow spinning icon appears in the left menu; once it finishes it turns green ✅. When you look at your README, you will see the updated article list.

7. Demo 👀

You can see a working example of the system described in this article on my own GitHub profile. Medium and dev.to articles update automatically every morning.

👉 github.com/yasinatesim

The full source code, including fetch_articles.py and update-articles.yml, is available in the repo below:

👉 github.com/yasinatesim/yasinatesim

Feedback 📬

While writing this article, I used Claude Opus 4.6 Thinking for proofreading and research, and Gemini 3.1 Flash Image Preview (Nano Banana 2) for generating the diagrams.

Feedback, suggestions, and corrections are always welcome. You can reach me through the social media links on my website or on LinkedIn.

Best, Yasin 🤗

Resources 📚

Docs

Tools

crontab.guru -- Visually test cron expressions
GitHub Secrets Docs -- Store API keys securely

Inspiring README Examples

Micro Frontend Architecture (with React Examples) 🧩

Yasin ATEŞ — Sun, 08 Mar 2026 15:16:08 +0000

As a product grows, so does the organization building it. Different business domains emerge, teams split up, and each team develops its own pace and priorities. But if the codebase stays in one piece, every small change requires coordination and every deployment affects the entire organization.

That is where Micro Frontend comes in.

In this article I will explain micro frontend architecture from the ground up. Instead of handing you a ready-made library list, I wanted to explain the underlying logic. The examples are written in React, but the architectural principles I cover (isolation, event bus, integration approaches) can be applied with any framework. I chose React to show the full picture in one consistent language.

I have a personal connection to this topic. At one of the companies I worked at, I had the chance to be a maintainer on an open-source micro frontend framework called VoltranJS. That experience let me understand this architecture deeply, both in theory and in practice.

1. What Is Micro Frontend? 🤔

Micro Frontend is an architecture that breaks a large and complex frontend application into small pieces that can be developed independently, deployed independently, and updated without blocking each other. Each of these independent pieces is called a micro app.

🎯 In short: what microservices do for the backend, Micro Frontend does for the frontend.

Unlike backend microservices, however, micro apps share the same browser environment (same DOM, same window, same localStorage). Isolation does not come for free here; it must be provided deliberately.

Consider an e-commerce site. Home page, product listing, product detail, cart, checkout -- these are all areas with different business logic, different requirements, and different rates of change. Micro frontend makes it possible for each of these areas to:

★ Live in its own repository

★ Have its own CI/CD pipeline

★ Be deployed independently

★ Use different technology stacks if desired

⚠️ The freedom to use different technology stacks is theoretical. In practice, most successful micro frontend implementations standardize around a single main framework. I cover this in detail in Section 3 -- Disadvantages.

2. Monolith vs Micro Frontend 🆚

┌─────────────────────────────────────────────┐
│           Single Large Frontend App         │
│  ┌────────┐  ┌──────────┐  ┌─────────────┐  │
│  │ Header │  │ Products │  │  Checkout   │  │
│  └────────┘  └──────────┘  └─────────────┘  │
│    One Repo -- One Deploy -- All Teams      │
└─────────────────────────────────────────────┘

Problems that arise as a monolith grows:

★ Every small change requires deploying the entire application

★ Multiple teams working on the same codebase leads to constant merge conflicts

★ Different teams' different speed requirements get squeezed into a single pipeline

★ Modernizing legacy code forces an all-or-nothing decision

★ One team's bug can bring down the entire application

Micro frontend addresses these problems like this:

┌──────────────┐  ┌───────────────┐  ┌────────────┐
│    Header    │  │   Products    │  │    Cart    │
│    Team A    │  │    Team B     │  │   Team C   │
│ Independent  │  │ Independent   │  │Independent │
│   Deploy     │  │   Deploy      │  │  Deploy    │
└──────────────┘  └───────────────┘  └────────────┘
        │                │                  │
        └────────────────┴──────────────────┘
                         │
               ┌──────────────────┐
               │     Main App     │
               └──────────────────┘

3. Advantages and Disadvantages ⚖️

3.1 Advantages

★ Independent Deployment
Each team can ship their own micro app without waiting for other teams. A payment team's deployment does not affect the cart team's release schedule.

★ Team Autonomy
Each team can make its own technology decisions. Onboarding gets easier; a new developer only needs to learn their own micro app, not the entire application.

★ Fault Isolation
If a micro app crashes, error boundaries keep the others running. In a monolith, a single bug can bring down the whole page.

★ Incremental Modernization
Instead of rewriting a legacy application all at once, you can migrate piece by piece to modern technology. Old pages keep working while new micro apps are added one by one.

★ Parallel Development
Multiple teams can work on different micro apps at the same time, completing their sprints without blocking each other.

★ Easy A/B Testing
You can run region-based or user-based tests simply by deploying a different version of the relevant micro app.

3.2 Disadvantages

★ Increased Operational Complexity
Each micro app means a separate service: separate repo, separate CI/CD, separate monitoring. This overhead can be heavy for small teams.

★ Initial Load Performance
Each micro app means a separate JavaScript bundle. HTTP/2 multiplexing reduces the multi-request problem, but total JavaScript parse and execution time still increases. A poorly configured dependency strategy can bloat the page.

★ Design Inconsistency
If each team manages its own CSS, visual inconsistencies build up over time. A shared design system becomes mandatory.

★ Test Complexity
Integration and end-to-end tests require keeping multiple services running at the same time.

★ Dependency Conflicts
If different micro apps use incompatible library versions, two instances of the same library end up running in the browser simultaneously.

★ Multiple Framework Cost
The freedom for each team to use its own framework is theoretical. In practice, each additional technology stack loads its own runtime (framework core ~40-50 kb + router ~15-20 kb + state library ~10-30 kb gzipped), developers cannot move between teams, the UI kit has to be written separately for each framework, and the test matrix multiplies. Most successful implementations standardize around a single main framework.

★ Drawing Wrong Boundaries
If domain boundaries are drawn based on technology preferences rather than business requirements, unnecessary network requests and data duplication become inevitable. This is the most common structural mistake.

4. Core Concepts 🧱

4.1 Main App

This is the shell of the micro frontend architecture -- the central structure that brings all other micro apps together. Routing, navigation, and shared layout live in this layer. Authentication and global state are typically managed here as well. The main app also takes on the orchestration role, deciding how and where micro apps are composed. That composition can happen client-side, server-side, or at the edge.

Some micro frontend resources also call this the "shell" or "container." I used "Main App" throughout this article to avoid confusion with other uses of those words in software. You will see "shell" in the code examples because that is the common directory naming convention.

4.2 Micro App

A small frontend application responsible for a specific business domain, deployed independently. In Module Federation terminology it is also called a remote.

💡 The word "remote" is heavily overloaded in software, so outside the Module Federation section I use "Micro App" throughout the article.

4.3 Routing

The main app is responsible for unmounting the current micro app and mounting the new one when the route changes. There are two common patterns:

★ Main-app-side routing: All URL navigation is defined in the main app. The micro app only knows its mount point; it has no idea which URL it will be shown on. This provides centralized control and keeps micro apps fully isolated.

// shell/src/App.js -- main app
import { BrowserRouter, Routes, Route } from 'react-router-dom';
import { Suspense, lazy } from 'react';

// Micro apps are lazy-loaded (integration details in Section 7)
const Home    = lazy(() => import('homeApp/Home'));
const Catalog = lazy(() => import('catalogApp/Catalog'));
const Cart    = lazy(() => import('cartApp/Cart'));

const Fallback = ({ name }) => (
  <div className="mfe-skeleton">{name} loading...</div>
);

export default function App() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={
          <Suspense fallback={<Fallback name="Home" />}>
            <Home />
          </Suspense>
        } />
        <Route path="/products/*" element={
          <Suspense fallback={<Fallback name="Products" />}>
            <Catalog />
          </Suspense>
        } />
        <Route path="/cart" element={
          <Suspense fallback={<Fallback name="Cart" />}>
            <Cart />
          </Suspense>
        } />
      </Routes>
    </BrowserRouter>
  );
}

★ Micro-app-side routing: The micro app manages its own internal navigation (for example, moving from a product list to a product detail page). The main app only knows which root URL to mount the micro app at; everything inside is the micro app's responsibility.

// catalog-micro-app/src/CatalogApp.js
import { Routes, Route } from 'react-router-dom';
import ProductList from './ProductList';
import ProductDetail from './ProductDetail';

// The main app mounts this micro app under "/products/*".
// The micro app manages its own nested routes.
export default function CatalogApp() {
  return (
    <Routes>
      <Route index element={<ProductList />} />
      <Route path=":id" element={<ProductDetail />} />
    </Routes>
  );
}

💡 The two patterns are not mutually exclusive. The main app handles top-level routing (which micro app to show) while the micro app handles its own nested routes. Together, the flow looks like this:

URL: /products/abc-123

Main app routing (App.js):
  "/products/*" → mount <Catalog /> micro app

Micro app routing (CatalogApp.js):
  "/products/"       → <ProductList />     (index route)
  "/products/:id"    → <ProductDetail />   ← abc-123 matches here

The "/products/*" wildcard in the main app lets the micro app recognize its own nested paths. The main app answers "which micro app," the micro app answers "which sub-page."

5. How Is Isolation Achieved? 🔒

One of the most critical challenges in micro frontend is isolation: how do you prevent one micro app's CSS or JavaScript from overriding another's?

5.1 CSS Isolation

The browser's global CSS scope is shared by all micro apps. If the same class name is used in two different micro apps, one will override the other.

.container { background: blue; }  /* Micro App A */
.container { background: red; }   /* Micro App B -- overrides the rule above! */

The most practical and widespread solution is CSS Modules. With CSS Modules you give the file a .module.css extension, and at build time an automatic hash is added to every class name. So instead of .container you get something like .ProductList_container__3xMq2, making collisions impossible. SCSS Modules use the same isolation mechanism (.module.scss extension) and add SCSS features like variables, nesting, and mixins on top. I used SCSS Modules in the examples throughout this article.

/* ProductList.module.scss */
.container {
  padding: 1rem;
  border-radius: 8px;

  .title {
    font-size: 1.5rem;
    color: #111827;
  }

  &:hover { background: #f9fafb; }

  $primary: #4f46e5;

  .badge {
    background: $primary;
    color: white;
    padding: 2px 8px;
    border-radius: 999px;
  }
}

// ProductList.js
import styles from './ProductList.module.scss';

function ProductList() {
  return (
    <div className={styles.container}>
      <h2 className={styles.title}>Products</h2>
      <span className={styles.badge}>New</span>
    </div>
  );
}
// Rendered to DOM as: <div class="ProductList_container__3xMq2">

💡 Alternative approaches: CSS-in-JS libraries (styled-components, Emotion) or Shadow DOM also provide isolation. In a micro frontend context, though, SCSS Modules offer the lowest runtime cost and the broadest tooling compatibility.

5.2 JavaScript Isolation

Global variables, properties on window, and localStorage are the most common sources of collisions.

// Micro App A
window.currentUser = { id: 1, name: 'Alice' };

// Micro App B overwrites Micro App A's data
window.currentUser = { id: 2, name: 'Bob' };

The correct approach:

window.__MFE__ = window.__MFE__ || {};

window.__MFE__.header = { currentUser: { id: 1, name: 'Alice' }, version: '1.2.3' };
window.__MFE__.cart   = { items: [], total: 0 };

★ For localStorage, use a prefix:

const PREFIX = 'mfe_header_';
localStorage.setItem(`${PREFIX}user`, JSON.stringify(user));
localStorage.getItem(`${PREFIX}user`);

⚠️ A namespace is only a naming convention; it is not enforced at runtime. Any micro app can still read or overwrite window.__MFE__.cart. This approach works only when every team respects the convention.

6. Communication with Event Bus 📡

Micro apps should not import each other directly; that creates coupling and breaks independent deployment. Communication should be event-based. The CustomEvent API on window is all you need for this:

const bus = {
  emit(event, data) {
    window.dispatchEvent(new CustomEvent(event, { detail: data }));
  },

  on(event, handler) {
    /*
      wrapper:
        (1) extracts e.detail
        (2) stores the reference for cleanup
    */
    const wrapper = (e) => handler(e.detail);

    window.addEventListener(event, wrapper);
    return () => window.removeEventListener(event, wrapper); // cleanup
  },
};

export { bus };

You publish this package as @org/event-bus in your private npm registry (GitHub Packages, npm org scope, Verdaccio, etc.). How the package is distributed to micro apps (Module Federation shared config, vendor CDN, etc.) depends on the integration approach you choose; I will cover those in Section 7.

★ Why CustomEvent?

Because it lives on window, events emitted from different bundles naturally see each other on the same page. No extra instance-sharing is needed. When any micro app calls bus.emit() from its own bundle, the bus.on() listeners in other micro apps will catch it. Zero dependencies, native browser API.

6.1 Usage

💡 Naming convention: The format mfe:{microapp}:{action} is recommended. The mfe: prefix prevents collisions (and typically matches the name of the micro frontend framework in use), the middle segment identifies the source, and the trailing segment describes the action.

// ProductsApp.jsx
import React from "react";
import { bus } from "@org/event-bus";

const products = [
  { id: 1, name: "Keyboard", price: 500 },
  { id: 2, name: "Mouse", price: 300 },
];

export default function ProductsApp() {
  const addToCart = (product) => {

    // ★ We are sending the product info
    bus.emit("mfe:cart:add", {
      productId: product.id,
      price: product.price,
      quantity: 1,
    });
  };

  return (
    <div>
      <h2>Products</h2>
      {products.map((product) => (
        <div key={product.id}>
          <span>
            {product.name} - ${product.price}
          </span>
          <button onClick={() => addToCart(product)}>
            Add to Cart
          </button>
        </div>
      ))}
    </div>
  );
}

// CartApp.jsx
import React, { useEffect, useState } from "react";
import { bus } from "@org/event-bus";

export default function CartApp() {
  const [cartItems, setCartItems] = useState([]);

  useEffect(() => {
    const handleAddToCart = (item) => {
      setCartItems((prev) => {
        const existing = prev.find(p => p.productId === item.productId);

        if (existing) {
          return prev.map(p =>
            p.productId === item.productId
              ? { ...p, quantity: p.quantity + 1 }
              : p
          );
        }

        return [...prev, item];
      });
    };

    // ★ We are receiving the product info sent from the other component and running cleanup

    /* This way:
      ✔ Listener is removed when the component unmounts
      ✔ No memory leaks
      ✔ Multiple mount/unmount cycles are safe
   */
    const unsubscribe = bus.on("mfe:cart:add", handleAddToCart);
    return unsubscribe;
  }, []);

  return (
    <div>
      <h2>Cart</h2>
      {cartItems.map((item) => (
        <div key={item.productId}>
          Product: {item.productId} |
          Quantity: {item.quantity} |
          Price: ${item.price}
        </div>
      ))}
    </div>
  );
}

6.2 Communication Scenarios

** ★ Client to Client: Two micro apps on the same page communicate**

import { bus } from '@org/event-bus';

function ProductCard({ product }) {
  return (
    <button onClick={() =>
      bus.emit('mfe:cart:add', { productId: product.id, price: product.price })
    }>
      Add to Cart
    </button>
  );
}

** ★ Client to Server to Notification: Notifying other micro apps after a backend action**

Sending a request to the server does not require the event bus; a standard fetch is enough. But when the result needs to be broadcast to other micro apps, that is where the event bus comes in:

// checkout micro app
import { bus } from '@org/event-bus';

async function initiatePayment(cartId, paymentMethod) {
  // Standard fetch request to the server
  const res = await fetch('/api/checkout/initiate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ cartId, paymentMethod }),
  });
  const { orderId } = await res.json();

  // Broadcast the result to other micro apps via event bus
  bus.emit('mfe:order:created', { orderId });
}

7. Integration Approaches 🔗

There are multiple ways to compose micro apps together. Each has different strengths and weaknesses; choosing the right one depends on your project's needs.

7.1 Build-Time Integration

Micro apps are published as npm packages, and the main app includes them in a single bundle at build time. The package being published here is the micro app itself -- all business logic, state, and API calls are embedded into the main app's build.

Micro App A → npm publish → @org/header@1.2.3
Main App → npm install @org/header → build → deploy

★ Simple to set up

★ The micro app cannot be updated without rebuilding the main app -- true independent deployment is not possible

7.2 Run-Time Client-Side Integration

Micro apps are loaded dynamically at runtime in the browser. This can be done in two ways: the manual approach and Module Federation.

7.2.1 Manual Approach

In its simplest form, each micro app's bundle is fetched from a CDN and mounted into the page:

async function bootstrapApp() {
  const [HeaderModule, ProductsModule] = await Promise.all([
    import('https://header.cdn.example.com/header.esm.js'),
    import('https://products.cdn.example.com/products.esm.js'),
  ]);

  HeaderModule.default.mount(document.getElementById('header'));
  ProductsModule.default.mount(document.getElementById('products'));
}

★ Each micro app can be deployed completely independently

★ Initial load time increases

★ Dependency sharing (avoiding duplicate loading of common libraries like React) must be managed manually by the developer

That manual management problem leads us to the shared dependency problem and Module Federation.

7.2.2 The Shared Dependency Problem

If every micro app bundles its own copy of React and similar libraries, the user downloads the same code multiple times. This wastes bandwidth and causes two separate instances of the same library to run on the page at the same time.

header.bundle.js    → React (~42kb gzipped) + own code (8kb)
products.bundle.js  → React (~42kb gzipped) + own code (15kb)
cart.bundle.js      → React (~42kb gzipped) + own code (6kb)
──────────────────────────────────────────────────────────────
3 copies loading, 2 of them unnecessary → 84kb wasted

** ★ Vendor Bundle Approach (Pre-Module Federation)**

Before Module Federation, the common solution was to serve shared libraries as a single vendor bundle (vendor.js) from a CDN, and have micro apps use webpack's externals config to exclude those libraries from their own bundles. The externals setting tells webpack not to include a library in the bundle and instead read it from the global scope at runtime (for example window.React):

// Micro app webpack.config.js (pre-Module Federation approach)
module.exports = {
  externals: {
    react: 'React',           // import React → taken from window.React
    'react-dom': 'ReactDOM',  // import ReactDOM → taken from window.ReactDOM
  },
};

<!-- Main app layout -- loads vendor libraries into global scope -->
<script src="https://cdn.example.com/vendor/react.18.2.0.min.js"></script>
<script src="https://cdn.example.com/vendor/react-dom.18.2.0.min.js"></script>

<!-- Micro app bundles no longer include React; they use window.React -->
<script src="https://header.cdn.example.com/header.bundle.js"></script>
<script src="https://products.cdn.example.com/products.bundle.js"></script>

This works, but management is manual: you have to centrally coordinate which library is used at which version. Module Federation automates this process.

7.2.3 Module Federation

Module Federation, introduced with webpack 5, was the most game-changing innovation in the micro frontend world. It solves the dependency-sharing problem at runtime, at the webpack level.

Main App (Host): The central application that consumes modules from other applications. Called the "host" in Module Federation terminology.

Remote (Micro App): An independent application that exposes its own modules. Each remote produces a remoteEntry.js file. This file works like a manifest, declaring which modules the remote exposes and where their JavaScript files are located. The main app downloads this manifest first on page load, then requests the actual code for the needed modules on demand.

Shared: Common dependencies. When marked with singleton: true, only a single instance of a library like React is guaranteed to load.

Remote Configuration:

// products-app/webpack.config.js (micro app)
const { ModuleFederationPlugin } = require('webpack').container;

module.exports = {
  output: {
    publicPath: 'https://products.cdn.example.com/',
  },
  plugins: [
    new ModuleFederationPlugin({
      name: 'productsApp',
      filename: 'remoteEntry.js',
      exposes: {
        './ProductList':   './src/components/ProductList',
        './ProductDetail': './src/components/ProductDetail',
      },
      shared: {
        react:       { singleton: true },
        'react-dom': { singleton: true },
      },
    }),
  ],
};

Main App (Host) Configuration:

// shell-app/webpack.config.js (main app)
const { ModuleFederationPlugin } = require('webpack').container;

module.exports = {
  plugins: [
    new ModuleFederationPlugin({
      name: 'shell',
      remotes: {
        productsApp: 'productsApp@https://products.cdn.example.com/remoteEntry.js',
        cartApp:     'cartApp@https://cart.cdn.example.com/remoteEntry.js',
        headerApp:   'headerApp@https://header.cdn.example.com/remoteEntry.js',
      },
      shared: {
        react:       { singleton: true },
        'react-dom': { singleton: true },
      },
    }),
  ],
};

Using a Remote Module in the Main App:

// shell-app/src/App.js (main app)
import React, { Suspense, lazy } from 'react';

// Remote modules are loaded with lazy import
const ProductList = lazy(() => import('productsApp/ProductList'));
const CartBadge   = lazy(() => import('cartApp/CartBadge'));
const Header      = lazy(() => import('headerApp/Header'));

const Fallback = ({ name }) => (
  <div className="mfe-skeleton">{name} loading...</div>
);

export default function App() {
  return (
    <>
      <Suspense fallback={<Fallback name="Header" />}>
        <Header />
      </Suspense>

      <main>
        <Suspense fallback={<Fallback name="Products" />}>
          <ProductList />
        </Suspense>
      </main>

      <Suspense fallback={<Fallback name="Cart" />}>
        <CartBadge />
      </Suspense>
    </>
  );
}

When remote modules are wrapped with lazy, the Suspense fallback is shown while loading. Once the remote's JavaScript is downloaded, the actual component renders.

As of 2024, Module Federation has evolved into an independent project (module-federation/core) that can be used with bundlers beyond webpack.

7.3 Which Approach Should You Choose?

★ Build-time integration is the simplest to set up and type safety comes naturally, but it cannot provide independent deployment. The main app has to be rebuilt with every update. It can work for small teams or rarely-changing micro apps, but it becomes a bottleneck as you scale.

★ Manual client-side integration offers independent deployment; each micro app is served from its own CDN and loaded at runtime. However, dependency sharing is entirely the developer's responsibility -- you have to manually coordinate externals and CDN settings to prevent duplicate loading of libraries like React. Initial load time also increases.

★ Module Federation offers the same runtime independence while automating dependency sharing. singleton: true guarantees that shared libraries load only once. It works with webpack and, increasingly, with other bundlers.

8. Design System Management 🎨

When multiple teams work independently, buttons end up different colors, spacing becomes inconsistent, and typography standards drift.

The solution is straightforward: a shared design system.

8.1 CSS Variables (Custom Properties): Single Source of Truth

Defining design decisions (color, spacing, typography, border radius) as CSS custom properties is the simplest way to maintain consistency across all micro apps. Instead of hardcoding values in CSS, micro apps read from these variables:

/* @org/design-system/variables.css */
:root {
  --color-primary:       #4F46E5;
  --color-primary-hover: #4338CA;
  --color-success:       #10B981;
  --color-danger:        #EF4444;
  --color-text:          #111827;
  --color-text-muted:    #6B7280;
  --color-bg:            #FFFFFF;
  --color-bg-secondary:  #F9FAFB;
  --color-border:        #E5E7EB;

  --space-xs: 0.25rem;
  --space-sm: 0.5rem;
  --space-md: 1rem;
  --space-lg: 1.5rem;
  --space-xl: 2rem;

  --font-family:    'Inter', system-ui, sans-serif;
  --font-size-sm:   0.875rem;
  --font-size-base: 1rem;
  --font-size-lg:   1.25rem;
  --font-size-xl:   1.5rem;

  --radius-sm:   4px;
  --radius-md:   8px;
  --radius-lg:   12px;
  --radius-full: 999px;

  --color-skeleton:      #F0F0F0;
  --color-skeleton-wave: #E0E0E0;
}

/* products-micro-app/ProductCard.module.scss */
.card {
  background:    var(--color-bg);
  border:        1px solid var(--color-border);
  border-radius: var(--radius-md);
  padding:       var(--space-md);

  .title { font-size: var(--font-size-lg);  color: var(--color-text); }
  .price { color: var(--color-primary);     font-size: var(--font-size-xl); }
}

The advantage of this approach: when a brand color changes, you update only the variables file, and all micro apps automatically pick up the new values.

8.2 Shared UI Kit: npm Package

Beyond variables, shared components (Button, Input, Modal, Card) are published as an npm package. Micro apps add it as a dependency. What is shared here as an npm package is strictly presentational components with no business logic; the micro apps themselves continue to be deployed independently.

// products micro app
import { Button, Card } from '@org/ui-kit';

function ProductCard({ product }) {
  return (
    <Card padding="md" bordered>
      <h3>{product.name}</h3>
      <Button variant="primary" onClick={() => addToCart(product)}>
        Add to Cart
      </Button>
    </Card>
  );
}

The UI kit is managed with semantic versioning. For minor updates (adding a new component), micro apps can upgrade at their own pace. For major updates (breaking changes), all teams should be given a reasonable migration window.

💡 The approach that works best in practice: load CSS variables in the layout, distribute the UI kit as an npm package, and give all teams 2-3 sprints for major version migrations.

9. When to Use It, When Not To 🤓

The core question that determines whether to adopt micro frontend is: Are your teams' business domains sufficiently separated?

Based on my experience and common industry patterns, micro frontend starts delivering value when there are multiple independent teams with clear domain separation. There is no hard number, but for single-team or very small organizations, the operational overhead typically outweighs the benefits.

9.1 When Micro Frontend Is a Good Fit

★ There are clear boundaries between different business domains (checkout, catalog, search, account) managed by separate teams

★ Teams have started blocking each other's deployments

★ Different areas have significantly different rates of change

★ A large legacy application needs to be modernized piece by piece

★ A/B tests need to run frequently and independently in a specific area of the page

★ Teams want full ownership of their own release schedule

9.2 When Micro Frontend Is Not a Good Fit

★ The application is still in a growth phase and domain boundaries are not yet clear; wrongly drawn boundaries will create large refactoring costs later

★ Teams are still making decisions together on every feature; architecture alone does not solve organizational problems

★ The goal is shipping a fast MVP; product first, architecture second

★ Performance and bundle size are the primary constraints; every additional micro app adds overhead

★ Developer experience and local setup complexity cannot be tolerated

What Is Next? 🗺️

This article covered the core concepts of micro frontend architecture, integration approaches, and the key things to watch out for. If you want to keep exploring, here are some topics worth looking into:

Server-Side Integration and Hydration
Rendering micro apps on the server, composing the layout server-side, and making it interactive on the client (hydration). SSR and CSR micro apps coexisting on the same page, graceful degradation strategies, and resolving hydration mismatch issues.

Performance and Monitoring
Per-micro-app Core Web Vitals measurement and reporting. Error boundaries to keep a crashing micro app from affecting others. Skeleton placeholders to prevent Cumulative Layout Shift. Above-the-fold/below-the-fold lazy loading. Critical CSS inlining. INP (Interaction to Next Paint) measurement and optimization per micro app.

Local Development Experience
Day-to-day development in a micro frontend setup: running a micro app in standalone mode, testing main app integration with mock micro apps, full environment setup with Docker Compose. The answer to: "Do I really have to spin up 10 services just to work on my own micro app?"

Micro Frontend with Next.js
How Next.js's App Router, Server Components, and built-in SSR capabilities combine with micro frontend architecture. Module Federation's Next.js integration (@module-federation/nextjs-mf), page-based micro app separation, and using Next.js's own middleware layer as the main app.

Feedback 📬

While writing this article, I used Claude Opus 4.6 Thinking for proofreading, my own notes from my time as a VoltranJS maintainer combined with ChatGPT 5.2's deep research feature for sourcing and research, and Gemini 3 Pro Image Preview 2k (Nano Banana Pro) for generating the diagrams.

Feedback, suggestions, and corrections are always welcome. You can reach me through the social media links on my website or on LinkedIn.

Take care, Yasin 🤗

Resources 📚

Open Source Repos

Articles and Docs

Books

Micro Frontends in Action -- https://www.manning.com/books/micro-frontends-in-action
Building Micro-Frontends -- https://www.buildingmicrofrontends.com/
The Art of Micro Frontends -- https://www.packtpub.com/product/the-art-of-micro-frontends/9781800563568
Practical Module Federation -- https://module-federation.myshopify.com/products/practical-module-federation

Courses

Podcasts

yasinates.com is coming soon 😋

Yasin ATEŞ — Sun, 21 Jun 2020 08:47:06 +0000

Hello everyone 😀, this is my first post.

I will share the English of my articles on medium.com here.

I create the data on my website using the DEV API, medium.com API, and Github API services 😎

I will write my next article is about the publishing process of my website.

Hope to see you in new articles. 👋 👋

My medium profile: medium.com/@yasinatesim/

My personal website: yasinates.com

DEV Community: Yasin ATEŞ

Atomic Design in Practice: React and Storybook from Scratch 🧩

🧩 What Is Atomic Design?

🤔 Why Does It Matter?

⚛️ How Should You Think About Atomic Design in React?

🛠️ Setting Up the Project

Step 1: Scaffold the React project

Step 2: Add Storybook

📁 Setting Up the Folder Structure

🧪 Atom-Level Components

Button.jsx

Input.jsx

🧬 Molecule-Level Components

SearchBox.jsx

🏗️ Organism-Level Components

Header.jsx

ProductCard.jsx

📐 Template and Page Layers

MainLayout.jsx

🛍️ Sample Project: Building a Mini E-Commerce UI

Step 1: Create the mock product data

Step 2: Write the HomePage component

Step 3: Wire up the application entry point

Step 4: Add minimal styles

👀 Isolated Component Development with Storybook

Step 1: Write a story for Button

Step 2: Write a story for ProductCard

⚖️ Pros and Cons of Atomic Design

Pros

Cons

😅 Common Mistakes

🤔 When Should You Use It?

📬 Feedback

📚 References

Monorepo Architecture with pnpm Workspace, Turborepo & Changesets 📦

🏗️ What Is a Monorepo?

🔧 Setting Up a pnpm Workspace

Step 1: Install pnpm and Initialize the Project

Step 2: Create pnpm-workspace.yaml

Step 3: Configure the Root package.json

Step 4: Create the Project Structure

🔗 Cross-Package Dependency Management with the workspace Protocol

Variants of the workspace Protocol

Adding Dependencies Between Packages

⚡ Build Orchestration with Turborepo

Let's Set Up Turborepo

turbo.json Configuration

🦋 Version Management with Changesets

Step 1: Install Changesets

Step 2: Configure Changesets

Step 3: Create a Changeset

Step 4: Apply the Versions

Step 5: Publish

🚀 Automated NPM Publishing with GitHub Actions

Step 1: Create an NPM Token

Step 2: Add Tokens to GitHub Secrets

Step 3: Configure Repository Permissions

Step 4: Create the Release Workflow File

Step 5: Define the ci:publish Script

Changeset Bot

🎯 Demo: The Tuvix.js Monorepo Project

📬 Feedback

📚 Resources Used While Writing This Article

From Zero to Advanced: The Git Version Control System ☕️

What is Git? 🤔

A Brief History of Git 📖

Why Version Control? 🧐

How Does Git Work? ⚙️

Installation 💻

Configuration (git config) 🔧

★ Global Configuration

★ Local Configuration

★ Useful Additional Settings

★ Git Alias (Shortcuts)

★ Checking Configurations

Creating a Repository (git init) 📂

Tracking File Status (git status) 🔍

Adding Changes to the Staging Area (git add) ➕

Reviewing Staging Area Changes 👀

★ Change Types

`Button.jsx`

`Input.jsx`

`SearchBox.jsx`

`Header.jsx`

`ProductCard.jsx`

`MainLayout.jsx`

Step 2: Write the `HomePage` component

Step 1: Write a story for `Button`

Step 2: Write a story for `ProductCard`