Millions of developers have published extensions to the Chrome Web Store, and building one is more approachable than you might think.

In this handbook you'll go from zero to a published Chrome extension using TypeScript, React, and Plasmo, a modern framework that handles the repetitive setup and configuration so you can focus on writing features instead of boilerplate.

Along the way you'll touch the real Chrome extension APIs that power production extensions: querying tabs, creating tab groups, and passing messages between different parts of an extension.

By the end you'll have working code, a mental model of how extensions are structured, and everything you need to publish your own ideas to the Chrome Web Store.

Table of Contents

• What is Plasmo?

• What You Will Build

• What You Will Learn

• Prerequisites

• Project Setup

• Understanding the Background Script

• Building the Popup UI

• Testing Your Extension

• Next Steps and Extension Ideas

• Deploying to Chrome Web Store

What is Plasmo?

Plasmo is an open-source framework for building browser extensions. Think of it as the equivalent of Create React App or Next.js, but for Chrome extensions.

Without Plasmo, building a Chrome extension requires manually writing a manifest.json file, wiring up build tooling, and configuring TypeScript and React yourself. Plasmo handles all of that.

A single command scaffolds a working project with TypeScript and React already configured. It reads your package.json and generates the manifest.json Chrome requires, so you never edit it directly.

Moreover, changes to your source files automatically rebuild and reload the extension in Chrome during development, and full type safety including types for Chrome's own APIs is available out of the box.

Plasmo doesn't hide the Chrome extension concepts from you. You still use chrome.tabs, chrome.runtime, and the rest of the Chrome APIs directly. It just removes the tedious scaffolding so you can start building immediately.

What You Will Build

In this tutorial, you'll build a Tab Grouper Chrome extension from scratch.

This extension automatically organizes your browser tabs by grouping them based on their website domain.

Example Use Case

Imagine you have 20 tabs open: 5 from GitHub, 4 from YouTube, 3 from Stack Overflow, and 8 from other websites.

With one click, the Tab Grouper extension will automatically create colored groups for each website, making it straightforward to find and manage your tabs.

What You Will Learn

By completing this tutorial, you'll get hands-on experience in three areas.

First, Chrome Extension Basics: how extensions work under the hood, the anatomy of an extension (manifest, background scripts, popups), and how to load and test extensions in Chrome during development.

Second, Chrome APIs: specifically chrome.tabs for managing browser tabs, chrome.tabGroups for creating and customizing tab groups, and chrome.runtime for passing messages between different parts of your extension.

Third, Modern Web Development tooling: TypeScript for type-safe JavaScript, React for building the popup UI, and the Plasmo framework that ties it all together.

Prerequisites

You don't need to be an expert in any of these, but you'll have the smoothest experience if you're comfortable with basic JavaScript or TypeScript and have a general understanding of HTML and CSS.

Some familiarity with React is helpful but not required. The pop-up component we'll build is simple enough to follow even if you're new to it.

On the software side, you'll need Node.js version 18 or higher (download here), Google Chrome, a code editor (VS Code is recommended), and pnpm as your package manager.

Verify Your Setup

Open your terminal and run these commands to confirm everything is installed:

node --version
# Should output v18.0.0 or higher

npm --version
# Should output 9.0.0 or higher

Getting Help

If you get stuck, review the complete code in the repository, consult the Chrome Extension documentation, or ask for help in the community forums.

Ready to Begin?

In the next section, you'll set up your development environment and create your first Chrome extension project.

Let's get started!

Project Setup

In this section, you'll use Plasmo to scaffold your Chrome extension project, then customize it for the Tab Grouper.

Rather than creating files manually, you'll let Plasmo generate a starter project with all required configuration, then explore what was created before customizing it for our needs.

Step 1: Install pnpm (Recommended)

Plasmo officially recommends pnpm for faster installs and better disk space usage. Check if you already have it:

pnpm --version

If you see a version number, skip to Step 2.

If you get "command not found", install it with:

npm install -g pnpm

Step 2: Create Your Extension Project

Run this command to create a new Plasmo project:

pnpm create plasmo tab-grouper

You'll see:

🟣 Creating a new Plasmo extension
📁 Project name: tab-grouper
? Extension description: (Give your extension a nice description)
? Author name: (Your Name)

Plasmo will then scaffold the project and install dependencies automatically. You might be prompted to enter a description and author name.

Fill these in however you like.

Step 3: Navigate to Your Project

cd tab-grouper

Step 4: Explore What Was Created

List the files that Plasmo generated:

ls -la

You should see something like this:

tab-grouper/
├── .git/                 # Git repository (already initialized!)
├── .github/              # GitHub Actions workflows
├── assets/
│   └── icon.png          # Default Plasmo icon 
├── node_modules/         # Dependencies (already installed!)
├── package.json          # Project configuration
├── popup.tsx             # Default popup 
├── .prettierrc.cjs       # Code formatting rules
├── .gitignore            # Git ignore rules
├── README.md             # Default readme
└── tsconfig.json         # TypeScript configuration

The key files to know about:

• assets/icon.png: The extension icon required by Chrome.

• package.json: Lists dependencies and scripts, and is where you configure the extension manifest.

• popup.tsx: The UI that appears when you click the extension icon.

• tsconfig.json: Contains TypeScript settings that are already correctly configured.

Step 5: Test the Default Extension

Make sure everything works before you customize it.

You can do this by starting the development server:

pnpm dev

You should see output like this:

🟣 Plasmo v0.90.5
🔴 The Browser Extension Framework
🔵 INFO   | Starting the extension development server...
🔵 INFO   | Building for target: chrome-mv3
🔵 INFO   | Loaded environment variables from: []
🟢 DONE   | Extension re-packaged in 1842ms! 🚀

View Extension:
📦 build/chrome-mv3-dev

Your extension is ready. Keep this terminal window open.

Plasmo watches for file changes and rebuilds automatically.

Step 6: Load the Extension in Chrome

Now load the extension into Chrome to test it:

1. Open Google Chrome

2. Go to chrome://extensions/

3. Enable Developer mode (toggle in top-right)

4. Click "Load unpacked"

5. Navigate to your project folder

6. Select the build/chrome-mv3-dev folder

7. Click "Select Folder"

Your extension should now appear in the list.

Step 7: Test the Default Popup

1. Click the puzzle piece icon in Chrome's toolbar

2. Find "tab-grouper" and pin it

3. Click the extension icon

You will see a default popup that says "Welcome to Plasmo!"

The extension is working. Now you can customize it.

Step 8: Update Extension Information

Open package.json in your editor. This file stores metadata about your project. name, version, description, dependencies, and scripts for building and running your extension.

Find these lines near the top:

{
  "name": "tab-grouper",
  "displayName": "tab-grouper",
  "version": "0.0.0",
  "description": "A basic Plasmo extension.",

Change them to:

{
  "name": "tab-grouper",
  "displayName": "Tab Grouper",
  "version": "1.0.0",
  "description": "A simple Chrome extension - group tabs by domain",

Save the file.

Step 9: Add Required Permissions (Critical!)

This is a critical step. Without permissions, your extension will fail with errors like:

TypeError: Cannot read properties of undefined (reading 'query')

Chrome extensions must declare which browser APIs they intend to use. In package.json, find the "manifest" section.

It looks like this:

"manifest": {
  "host_permissions": [
    "https://*/*"
  ]
}

Replace it with:

"manifest": {
  "permissions": [
    "tabs",
    "tabGroups"
  ]
}

Save the file. The tabs permission allows you to read tab information (required for chrome.tabs.query()), and tabGroups allows you to create and manage tab groups (required for chrome.tabGroups.update()).

Finding the right permissions for your own extensions:

The Chrome Extension Permissions Reference lists every available permission and what it unlocks.

Each API's documentation page also lists which permissions it requires, for example, the chrome.tabs API page specifies the "tabs" permission.

If you're using Plasmo, the Manifest Configuration docs explain how to add permissions through package.json.

As a general rule: if you're getting undefined errors when calling a Chrome API, a missing permission is the first thing to check.

Step 10: Verify Hot Reload Works

Plasmo automatically reloads your extension when you save changes.

Check the terminal where pnpm dev is running. After saving package.json you should see something like:

🔄 Reloading extension...
✅ Ready in 0.8s

Your project is now ready: a working extension loaded in Chrome, a development server running with hot reload, and the required permissions in place.

Leave the dev server running and the extension loaded as you work through the next sections. Your changes will reload automatically.

Section Summary

In this section you installed pnpm, scaffolded a new extension with pnpm create plasmo, explored the generated project structure, started the development server, loaded the extension in Chrome, and updated the extension metadata and permissions.

Next: You'll create the background script that handles the tab grouping logic.

Understanding the Background Script

The background script is the heart of your extension. It runs persistently behind the scenes and contains the core logic.

In this case, the code that groups your tabs by domain.

What is a Background Script?

A background script runs continuously even when the popup is closed.

It can listen to browser events like tabs opening, closing, or updating, perform tasks that don't require direct user interaction, and communicate with other parts of the extension by passing messages.

Think of it as the server-side of your extension. The popup is just a UI that talks to it.

Step 1: Create background.ts

Plasmo's scaffolding didn't create a background script by default, so you'll create this file from scratch. Create a new file called background.ts in your project root (the same level as popup.tsx):

export {}

// Background script - runs in the background and handles tab grouping logic

console.log("Tab Grouper background script loaded!")

// Listen for messages from the popup
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === "GROUP_TABS") {
    groupTabsByDomain()
    sendResponse({ success: true })
  }
  return true
})

The export {} at the top is required by Plasmo to treat this file as a module. Without it you may get errors about conflicting global variable declarations.

The console.log will help you verify the script loaded correctly (you'll see it in the extension's DevTools console). chrome.runtime.onMessage sets up a listener so the background script can receive instructions from the popup.

When it receives a "GROUP_TABS" message, it calls the grouping function.

You can read more about this messaging pattern in the Chrome Extensions documentation.

Step 2: Implement Tab Grouping Logic

Now add the main grouping function below the message listener:

async function groupTabsByDomain() {
  try {
    // Step 1: Get all tabs in the current window
    const tabs = await chrome.tabs.query({ currentWindow: true })

    // Step 2: Create a Map to organize tabs by domain
    const domainGroups = new Map<string, chrome.tabs.Tab[]>()

    // Step 3: Loop through each tab and group by domain
    tabs.forEach(tab => {
      // Skip tabs without URLs
      if (!tab.url) return

      // Extract the domain from the URL
      const domain = getDomainFromUrl(tab.url)

      // Skip invalid domains (like chrome:// pages)
      if (!domain) return

      // Add tab to the appropriate domain group
      if (!domainGroups.has(domain)) {
        domainGroups.set(domain, [])
      }
      domainGroups.get(domain)!.push(tab)
    })

    // Step 4: Create tab groups for each domain (only if 2+ tabs)
    for (const [domain, domainTabs] of domainGroups) {
      // Skip domains with only 1 tab
      if (domainTabs.length < 2) continue

      // Get all tab IDs
      const tabIds = domainTabs
        .map(t => t.id!)
        .filter(id => id !== undefined)

      if (tabIds.length === 0) continue

      // Create the tab group
      const groupId = await chrome.tabs.group({ tabIds })

      // Customize the group with a title and color
      await chrome.tabGroups.update(groupId, {
        title: domain,
        color: getColorForDomain(domain) // Randomized Tab Group colors.
      })
    }

    console.log(`Successfully grouped ${domainGroups.size} domains`)
  } catch (error) {
    console.error("Error grouping tabs:", error)
  }
}

The function starts by querying all tabs in the current window, then iterates over them to build a Map keyed by domain name.

Once every tab has been sorted into a domain bucket, it loops through the map and calls chrome.tabs.group() for any domain that has two or more tabs, then immediately customizes the resulting group with a title and color.

Domains with only a single tab are skipped. There's no point grouping a lone tab.

Step 3: Extract Domain Helper

Add a helper function to pull the hostname out of a URL:

function getDomainFromUrl(url: string): string | null {
  try {
    const urlObj = new URL(url)

    // Skip Chrome internal pages (chrome://, chrome-extension://)
    if (urlObj.protocol === "chrome:" || urlObj.protocol === "chrome-extension:") {
      return null
    }

    // Remove "www." prefix and return the hostname
    return urlObj.hostname.replace(/^www\./, "")
  } catch {
    // Return null if URL is invalid
    return null
  }
}

new URL(url) gives us a structured object to work with rather than string-parsing the URL manually.

The protocol check filters out Chrome's internal pages like chrome://extensions and chrome://settings, which extensions can't access.

The .replace(/^www\./, "") ensures that www.github.com and github.com are treated as the same domain rather than two separate groups.

The whole thing is wrapped in a try-catch so malformed URLs simply return null and get skipped.

In practice: https://www.github.com/user/repo becomes github.com, https://youtube.com/watch?v=123 becomes youtube.com, and chrome://extensions returns null.

Step 4: Color Assignment Helper

Add a function to deterministically assign a color to each domain:

function getColorForDomain(domain: string): chrome.tabGroups.ColorEnum {
  // Available colors in Chrome
  const colors: chrome.tabGroups.ColorEnum[] = [
    "blue", "red", "yellow", "green", "pink", "purple", "cyan", "orange"
  ]

  // Create a simple hash from the domain name
  let hash = 0
  for (let i = 0; i < domain.length; i++) {
    hash = domain.charCodeAt(i) + ((hash << 5) - hash)
  }

  // Return a color based on the hash
  return colors[Math.abs(hash) % colors.length]
}

Chrome supports eight colors for tab groups. Rather than assigning them randomly (which would change every time you group), this function hashes the domain name to a number and uses the modulo operator to pick a consistent index into the color array.

The result is that github.com always gets the same color across sessions, while different domains are likely to get different colors.

Complete background.ts File

Your complete background.ts should look like this:

export {}

console.log("Tab Grouper background script loaded!")

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === "GROUP_TABS") {
    groupTabsByDomain()
    sendResponse({ success: true })
  }
  return true
})

async function groupTabsByDomain() {
  try {
    const tabs = await chrome.tabs.query({ currentWindow: true })
    const domainGroups = new Map<string, chrome.tabs.Tab[]>()

    tabs.forEach(tab => {
      if (!tab.url) return
      const domain = getDomainFromUrl(tab.url)
      if (!domain) return

      if (!domainGroups.has(domain)) {
        domainGroups.set(domain, [])
      }
      domainGroups.get(domain)!.push(tab)
    })

    for (const [domain, domainTabs] of domainGroups) {
      if (domainTabs.length < 2) continue

      const tabIds = domainTabs
        .map(t => t.id!)
        .filter(id => id !== undefined)

      if (tabIds.length === 0) continue

      const groupId = await chrome.tabs.group({ tabIds })

      await chrome.tabGroups.update(groupId, {
        title: domain,
        color: getColorForDomain(domain)
      })
    }

    console.log(`Successfully grouped ${domainGroups.size} domains`)
  } catch (error) {
    console.error("Error grouping tabs:", error)
  }
}

function getDomainFromUrl(url: string): string | null {
  try {
    const urlObj = new URL(url)
    if (urlObj.protocol === "chrome:" || urlObj.protocol === "chrome-extension:") {
      return null
    }
    return urlObj.hostname.replace(/^www\./, "")
  } catch {
    return null
  }
}

function getColorForDomain(domain: string): chrome.tabGroups.ColorEnum {
  const colors: chrome.tabGroups.ColorEnum[] = [
    "blue", "red", "yellow", "green", "pink", "purple", "cyan", "orange"
  ]

  let hash = 0
  for (let i = 0; i < domain.length; i++) {
    hash = domain.charCodeAt(i) + ((hash << 5) - hash)
  }

  return colors[Math.abs(hash) % colors.length]
}

Testing the Background Script

If your development server isn't already running from the previous section, start it:

pnpm dev

To verify the background script loaded correctly, go to chrome://extensions, find "Tab Grouper Tutorial", and click the "service worker" link.

A DevTools console will open and you should see "Tab Grouper background script loaded!" confirming everything is wired up.

Building the Popup UI

The popup is the small window that appears when a user clicks your extension icon in the Chrome toolbar.

It can display information, provide buttons for actions, and show settings.

In this section you'll build a React-based popup that shows live tab statistics and triggers the grouping logic in the background script.

Step 1: Replace popup.tsx

When you ran pnpm create plasmo, a default popup.tsx was created that just displays a welcome message.

Open that file and replace all of its contents with this starting skeleton:

import { useState, useEffect } from "react"

function IndexPopup() {
  const [tabCount, setTabCount] = useState(0)
  const [groupCount, setGroupCount] = useState(0)
  const [isGrouping, setIsGrouping] = useState(false)

  return (
    <div>
      <h2>Tab Grouper</h2>
      <button>Group Tabs</button>
    </div>
  )
}

export default IndexPopup

Save the file and the extension will automatically reload.

The three state variables track the number of open tabs, the number of existing groups, and whether a grouping operation is currently in progress.

That last one lets us disable the button and show a loading state so users can't trigger multiple groupings at once.

Step 2: Load Statistics

Now add the logic to load tab and group counts when the popup opens. Add this inside the IndexPopup function, right after the state declarations:

// Load tab statistics when popup opens
useEffect(() => {
  loadStats()
}, [])

async function loadStats() {
  const tabs = await chrome.tabs.query({ currentWindow: true })
  const groups = await chrome.tabGroups.query({
    windowId: chrome.windows.WINDOW_ID_CURRENT
  })

  setTabCount(tabs.length)
  setGroupCount(groups.length)
}

The useEffect with an empty dependency array [] runs once when the component first mounts. In other words, every time the popup opens.

It calls loadStats, which queries Chrome for the current window's tabs and groups, then updates the state variables with the counts.

Step 3: Trigger Tab Grouping

Add the handler that sends a message to the background script when the button is clicked:

async function handleGroupTabs() {
  setIsGrouping(true)

  // Send message to background script
  await chrome.runtime.sendMessage({ type: "GROUP_TABS" })

  // Refresh statistics
  await loadStats()
  setIsGrouping(false)
}

chrome.runtime.sendMessage delivers the { type: "GROUP_TABS" } message to the listener we set up in background.ts.

After the background script finishes, we reload the statistics so the group count updates immediately, then re-enable the button.

Step 4: Build the UI

Replace the placeholder return statement with this complete, styled version:

return (
  <div style={{
    width: 300,
    padding: 20,
    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif'
  }}>
    {/* Header */}
    <div style={{ marginBottom: 20 }}>
      <h2 style={{ margin: 0, fontSize: 20, fontWeight: 600 }}>
        🗂️ Tab Grouper
      </h2>
      <p style={{ margin: "8px 0 0", fontSize: 13, color: "#666" }}>
        Organize your tabs by domain
      </p>
    </div>

    {/* Statistics */}
    <div style={{
      display: "flex",
      gap: 12,
      marginBottom: 20,
      padding: 12,
      background: "#f5f5f5",
      borderRadius: 8
    }}>
      <div style={{ flex: 1 }}>
        <div style={{ fontSize: 24, fontWeight: 600, color: "#333" }}>
          {tabCount}
        </div>
        <div style={{ fontSize: 12, color: "#666" }}>
          Open Tabs
        </div>
      </div>
      <div style={{ flex: 1 }}>
        <div style={{ fontSize: 24, fontWeight: 600, color: "#0066ff" }}>
          {groupCount}
        </div>
        <div style={{ fontSize: 12, color: "#666" }}>
          Tab Groups
        </div>
      </div>
    </div>

    {/* Group Button */}
    <button
      onClick={handleGroupTabs}
      disabled={isGrouping}
      style={{
        width: "100%",
        padding: "12px 16px",
        fontSize: 14,
        fontWeight: 500,
        color: "white",
        background: isGrouping ? "#ccc" : "#0066ff",
        border: "none",
        borderRadius: 8,
        cursor: isGrouping ? "not-allowed" : "pointer",
        transition: "background 0.2s"
      }}
    >
      {isGrouping ? "Grouping..." : "🗂️ Group Tabs by Domain"}
    </button>

    {/* Footer */}
    <div style={{
      marginTop: 16,
      padding: 12,
      fontSize: 12,
      color: "#666",
      background: "#fff9e6",
      borderRadius: 6,
      border: "1px solid #ffe066"
    }}>
      💡 <strong>Tip:</strong> This will group all tabs in this window by their website domain.
    </div>
  </div>
)

The UI has four parts: a header with the extension title and a short description, a statistics box showing the live tab and group counts side by side, the main action button (which grays out and changes text to "Grouping..." while work is in progress), and a tip box at the bottom.

This tutorial uses inline styles for simplicity. In a production extension, you'd likely reach for CSS modules, Tailwind, or styled-components instead.

Complete popup.tsx File

Your complete popup.tsx should look like this:

import { useState, useEffect } from "react"

function IndexPopup() {
  const [tabCount, setTabCount] = useState(0)
  const [groupCount, setGroupCount] = useState(0)
  const [isGrouping, setIsGrouping] = useState(false)

  useEffect(() => {
    loadStats()
  }, [])

  async function loadStats() {
    const tabs = await chrome.tabs.query({ currentWindow: true })
    const groups = await chrome.tabGroups.query({
      windowId: chrome.windows.WINDOW_ID_CURRENT
    })

    setTabCount(tabs.length)
    setGroupCount(groups.length)
  }

  async function handleGroupTabs() {
    setIsGrouping(true)
    await chrome.runtime.sendMessage({ type: "GROUP_TABS" })
    await loadStats()
    setIsGrouping(false)
  }

  return (
    <div style={{
      width: 300,
      padding: 20,
      fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif'
    }}>
      <div style={{ marginBottom: 20 }}>
        <h2 style={{ margin: 0, fontSize: 20, fontWeight: 600 }}>
          🗂️ Tab Grouper
        </h2>
        <p style={{ margin: "8px 0 0", fontSize: 13, color: "#666" }}>
          Organize your tabs by domain
        </p>
      </div>

      <div style={{
        display: "flex",
        gap: 12,
        marginBottom: 20,
        padding: 12,
        background: "#f5f5f5",
        borderRadius: 8
      }}>
        <div style={{ flex: 1 }}>
          <div style={{ fontSize: 24, fontWeight: 600, color: "#333" }}>
            {tabCount}
          </div>
          <div style={{ fontSize: 12, color: "#666" }}>
            Open Tabs
          </div>
        </div>
        <div style={{ flex: 1 }}>
          <div style={{ fontSize: 24, fontWeight: 600, color: "#0066ff" }}>
            {groupCount}
          </div>
          <div style={{ fontSize: 12, color: "#666" }}>
            Tab Groups
          </div>
        </div>
      </div>

      <button
        onClick={handleGroupTabs}
        disabled={isGrouping}
        style={{
          width: "100%",
          padding: "12px 16px",
          fontSize: 14,
          fontWeight: 500,
          color: "white",
          background: isGrouping ? "#ccc" : "#0066ff",
          border: "none",
          borderRadius: 8,
          cursor: isGrouping ? "not-allowed" : "pointer",
          transition: "background 0.2s"
        }}
      >
        {isGrouping ? "Grouping..." : "🗂️ Group Tabs by Domain"}
      </button>

      <div style={{
        marginTop: 16,
        padding: 12,
        fontSize: 12,
        color: "#666",
        background: "#fff9e6",
        borderRadius: 6,
        border: "1px solid #ffe066"
      }}>
        💡 <strong>Tip:</strong> This will group all tabs in this window by their website domain.
      </div>
    </div>
  )
}

export default IndexPopup

Testing Your Extension

Now that you have both the background script and popup UI built, it's time to verify that everything works together in Chrome.

Step 1: Make Sure the Dev Server is Running

If pnpm dev isn't already running from an earlier step, start it now:

pnpm run dev # or pnpm dev

Plasmo will build the extension into build/chrome-mv3-dev and watch for changes.

Step 2: Load the Extension in Chrome

If you haven't already loaded the extension, go to chrome://extensions/, enable Developer mode, click Load unpacked, and select the build/chrome-mv3-dev folder.

Once loaded you should see the extension listed with the name "Tab Grouper Tutorial", version "1.0.0", and status Enabled.

Step 3: Pin the Extension

Click the puzzle piece icon in the Chrome toolbar, find "Tab Grouper Tutorial", and click the pin icon to keep it visible.

The extension icon will now appear directly in your toolbar.

Step 4: Test the Extension

Test 1: Open Multiple Tabs

Open several tabs across a few domains so there's something to group:

1. https://github.com/topics, https://github.com/trending, https://github.com/explore

2. https://www.youtube.com/ and https://www.youtube.com/trending

3. https://stackoverflow.com/questions and https://stackoverflow.com/tags

Have at least 7 tabs open.

Test 2: Group the Tabs

Click the Tab Grouper extension icon. The popup should appear showing your open tab count (7 or more) and group count (probably 0).

Click "Group Tabs by Domain" and watch your tabs get organized into colored groups.

Test 3: Verify Groups

After clicking the button, GitHub tabs should be grouped together with a label like "github.com" and a consistent color, and YouTube tabs similarly.

Click the extension icon again, the group count should now show 2, while the tab count stays the same.

Step 5: Debug the Extension

If something doesn't work, Chrome's DevTools are your best friend.

To inspect the background script, go to chrome://extensions/, find your extension, and click the "service worker" link.

A DevTools console opens where you can look for the "Tab Grouper background script loaded!" message and any error output in red.

To inspect the popup, right-click the extension icon and select "Inspect popup". This opens DevTools for the popup specifically — check the Console tab for any errors there.

If nothing happens when you click the button, check the background script console for errors, confirm you have at least 2 tabs from the same domain, and verify the message is being sent (look in the popup console for any sendMessage failures).

If tabs aren't grouping, double-check that you added the tabs and tabGroups permissions to package.json and reloaded the extension after saving.

If you see "Extension cannot access chrome://...", that's expected behavior — extensions can't interact with Chrome's internal pages and the code skips them intentionally.

Step 6: Hot Reloading

One of the benefits of Plasmo is hot reloading, which allows you to update code in a running app instantly without needing to restart it manually.

Open popup.tsx, change the header emoji from 🗂️ to 📁, and save.

The extension reloads automatically.

Click the icon and you'll see the updated emoji immediately.

Hot reloading is advantageous because it speeds up development by letting you see changes in real time.

You can change the emoji back afterward if you'd like to keep the extension consistent with the rest of the tutorial examples and screenshots.

Step 7: Test Edge Cases

It's worth testing a few scenarios to make sure the extension handles them gracefully.

If you close all tabs except one and click "Group Tabs", nothing should happen. The extension requires at least two tabs from the same domain to form a group. Opening chrome://extensions and chrome://settings and then grouping should also do nothing, since those pages are filtered out.

If you have one tab from reddit.com and one from freecodecamp.org, each domain appearing only once, no groups should be created.

Step 8: Production Build

When you're ready to share your extension, run:

pnpm run build

This creates a production-optimized version in build/chrome-mv3-prod, minified JavaScript, no development-only code, and smaller file size.

To verify the production build, go to chrome://extensions/, remove the development version, click "Load unpacked", and select build/chrome-mv3-prod. Test thoroughly before publishing.

The extension is lightweight (under 100 KB), only runs when you click the button, and has no background processes when idle.

Next Steps and Extension Ideas

Congratulations on building your first Chrome extension!

You now have a working tool that groups tabs by domain with one click, shows live statistics about open tabs and groups, and is built on modern tooling: TypeScript, React, and Plasmo following Chrome extension best practices.

The extension is a solid foundation. Here are some ideas for where to take it next.

1. Auto-Grouping

Instead of requiring a button click, you could automatically group new tabs as they're opened. You'd listen for the chrome.tabs.onCreated event in background.ts and trigger groupTabsByDomain() with a short delay to let the page URL load:

// In background.ts
chrome.tabs.onCreated.addListener(async (tab) => {
  // Wait a bit for the URL to load
  setTimeout(() => {
    groupTabsByDomain()
  }, 2000)
})

This gets into event listeners, asynchronous timing, and thinking carefully about when to fire — a good next step for understanding how background scripts can be more proactive.

2. Keyboard Shortcuts

You can trigger grouping without even opening the popup by adding a keyboard shortcut. Add a commands section to the manifest in package.json:

"manifest": {
  "commands": {
    "group-tabs": {
      "suggested_key": {
        "default": "Ctrl+Shift+G",
        "mac": "Command+Shift+G"
      },
      "description": "Group tabs by domain"
    }
  }
}

Then listen for the command in background.ts:

chrome.commands.onCommand.addListener((command) => {
  if (command === "group-tabs") {
    groupTabsByDomain()
  }
})

3. Category-Based Grouping

Rather than grouping by raw domain, you could group by category — putting GitHub, Stack Overflow, and npm together in a "Dev" group, for instance:

const categories = {
  social: ["facebook.com", "twitter.com", "instagram.com"],
  shopping: ["amazon.com", "ebay.com", "etsy.com"],
  dev: ["github.com", "stackoverflow.com", "npmjs.com"]
}

function getCategoryForDomain(domain: string): string {
  for (const [category, domains] of Object.entries(categories)) {
    if (domains.includes(domain)) {
      return category
    }
  }
  return "other"
}

4. Options Page

Plasmo makes it trivial to add a settings page by creating an options.tsx file.

This is where you'd let users toggle auto-grouping, choose between domain and category mode, or configure their own category mappings.

It's a good introduction to the Chrome Storage API and persisting user preferences.

function OptionsPage() {
  return (
    <div>
      <h1>Tab Grouper Settings</h1>
      <label>
        <input type="checkbox" />
        Enable auto-grouping
      </label>
      <label>
        <input type="checkbox" />
        Group by category instead of domain
      </label>
    </div>
  )
}

5. Tab Age Tracking

You could track when each tab was created and surface tabs that have been sitting untouched for a week or more, a nice way to encourage tab hygiene:

// Track tab creation times
const tabCreationTimes = new Map<number, number>()

chrome.tabs.onCreated.addListener((tab) => {
  if (tab.id) {
    tabCreationTimes.set(tab.id, Date.now())
  }
})

// Find old tabs (e.g., > 7 days)
function getOldTabs(): chrome.tabs.Tab[] {
  const sevenDaysAgo = Date.now() - (7 * 24 * 60 * 60 * 1000)
  return tabs.filter(tab => {
    const created = tabCreationTimes.get(tab.id!)
    return created && created < sevenDaysAgo
  })
}

6. Search Within Groups

A search bar in the popup would let users filter their open tabs by title, making it easy to jump to a specific tab:

const [searchQuery, setSearchQuery] = useState("")

const filteredTabs = tabs.filter(tab =>
  tab.title?.toLowerCase().includes(searchQuery.toLowerCase())
)

7. Export/Import Groups

You could let users save their current tab groups to a JSON file and restore them later. Useful for preserving a working session across restarts:

// Export
async function exportGroups() {
  const groups = await chrome.tabGroups.query({})
  const data = JSON.stringify(groups)
  const blob = new Blob([data], { type: 'application/json' })
  const url = URL.createObjectURL(blob)
  chrome.downloads.download({ url, filename: 'tab-groups.json' })
}

// Import
async function importGroups(file: File) {
  const text = await file.text()
  const groups = JSON.parse(text)
  // Restore groups...
}

8. Group Statistics Dashboard

An expanded popup could show browsing analytics, total tabs opened today, most-visited domain, and more:

function Statistics() {
  const [stats, setStats] = useState({
    totalTabs: 0,
    totalGroups: 0,
    mostUsedDomain: "",
    tabsToday: 0
  })

  return (
    <div>
      <h3>Browsing Statistics</h3>
      <p>Total tabs opened today: {stats.tabsToday}</p>
      <p>Most visited domain: {stats.mostUsedDomain}</p>
    </div>
  )
}

Learning Resources

If you want to go deeper, the official Chrome Extension docs are excellent and cover every API in detail.

The Chrome Extension Samples repository on GitHub has dozens of real examples to learn from. For Plasmo-specific questions, the Plasmo documentation and example repository are the best starting points, and the community is active on Plasmo Discord.

The React docs and TypeScript docs are worth bookmarking as reference material, and the React TypeScript Cheatsheet is handy when you're unsure about specific type patterns.

For community support, Stack Overflow's chrome-extension tag is well-monitored, and r/chrome_extensions on Reddit is a friendly place to ask questions.

Deploying to Chrome Web Store

Now that you've built and tested your extension, here's how to publish it and share it with the world.

What You'll Need

Before you can publish, you'll need a completed and tested extension, a Google account, a $5 USD one-time developer registration fee, and some store assets such as icons, screenshots, and a written description.

The $5 fee is a one-time charge (not annual) that Google uses to verify developer identity and reduce spam. It covers unlimited extension submissions and is processed immediately via Google Payments.

Step 1: Create a Production Build

Build your extension for production if you didn't do this before:

cd tab-grouper-tutorial
npm run build

This creates an optimized version in build/chrome-mv3-prod/. The production build minifies JavaScript and CSS for a smaller file size, strips out development-only code and console logs, and optimizes assets for faster loading.

Before uploading, load build/chrome-mv3-prod/ as an unpacked extension and test all features one more time to confirm nothing broke in the build process.

Step 2: Create Store Assets

Extension Icons

You'll need icons in three sizes: 128×128 pixels for the main store listing (required), 48×48 for the extension management page, and 16×16 for use as a favicon.

All should be PNG files with transparent backgrounds. Keep the design simple and recognizable at small sizes. Avoid putting text in the 16×16 version.

Figma is free and works well for this, as does Canva or GIMP.

Screenshots

Upload between 1 and 5 screenshots at either 1280×800 or 640×400 pixels (PNG or JPEG).

Show the extension in actual use rather than mockups. The popup with statistics, tabs being grouped, and the before/after state all work well.

Adding annotations to highlight key features helps users understand what they're looking at.

Promotional Images (Optional)

If you want to be featured on the store, you can also upload a small tile (440×280), large tile (920×680), and marquee image (1400×560). These are only needed if Google chooses to promote your extension.

Demo Video (Optional)

A short YouTube video (30–60 seconds) showing the extension in action can significantly increase conversions. Link to it in your store listing.

Step 3: Write Your Store Listing

Extension Name (45 character limit): Be clear and descriptive. "Tab Grouper - Organize Tabs by Domain" works well. Avoid keyword stuffing or excessive punctuation.

Summary (132 character limit): This is what appears in search results. Lead with what the extension does: "Automatically organize browser tabs by domain. One-click grouping keeps your workspace clean and productive."

Detailed Description (16,000 character limit): Start with what the extension does, list features clearly, explain how to use it, address privacy, and provide contact information. Here's a template you can adapt:

## What is Tab Grouper?

Tab Grouper automatically organizes your browser tabs by grouping them based on their website domain. No more hunting through dozens of tabs - everything is neatly organized.

## Features

- ✅ One-click tab grouping
- ✅ Automatic color-coding by domain
- ✅ Real-time statistics
- ✅ Works with all websites
- ✅ Lightweight and fast

## How to Use

1. Click the Tab Grouper icon in your toolbar
2. Click "Group Tabs by Domain"
3. Your tabs are instantly organized

## Why You Need This

If you regularly have numerous tabs open, finding the right one can waste valuable time. Tab Grouper solves this by automatically organizing tabs into colored groups, making navigation quick and straightforward.

## Privacy

This extension does not collect any personal data. It only accesses tab information locally to perform grouping. No data is sent to external servers.

## Support

Found a bug or have a suggestion? Contact us at support@example.com

Category: Choose Productivity for Tab Grouper. You can add additional languages later if you want to localize the listing.

Step 4: Register as a Chrome Web Store Developer

Go to the Chrome Web Store Developer Dashboard, sign in with your Google account, accept the Developer Agreement, and pay the $5 registration fee. Your account is activated within minutes.

Step 5: Submit Your Extension

In the Developer Dashboard, click "New Item" and upload your extension. You can either manually zip the build/chrome-mv3-prod/ folder or use Plasmo's package command:

# Option 1: Manual zip
cd build/chrome-mv3-prod
zip -r ../../tab-grouper.zip .

# Option 2: Use Plasmo package command
cd tab-grouper-tutorial
npm run package

Once uploaded, fill in all four sections of the store listing form: Product details (name, summary, description, category, language), Graphic assets (icon and screenshots), Privacy practices (see below), and Distribution (visibility, regions, pricing).

Single Purpose Description

Chrome requires each extension to have a single, clearly stated purpose. For Tab Grouper: "This extension organizes browser tabs by grouping them based on their domain name, helping users manage multiple open tabs efficiently."

Permission Justification

You'll need to justify each permission you declared. For tabs: "The tabs permission is required to read tab URLs and titles in order to group them by domain." For tabGroups: "The tabGroups permission is required to create and manage tab groups for organization."

Privacy Policy

Even though Tab Grouper doesn't collect personal data, Chrome may require a privacy policy. Host one on GitHub Pages or your personal website and link to it. Here's a minimal template:

# Privacy Policy for Tab Grouper

## Data Collection
Tab Grouper does not collect, store, or transmit any personal data.

## Permissions
- **tabs**: Used only to read tab URLs for grouping purposes
- **tabGroups**: Used only to create and manage tab groups

## Local Processing
All tab grouping happens locally in your browser. No data is sent to external servers.

## Contact
For questions: your-email@example.com

Last updated: [Current Date]

Step 6: Submit for Review

Before clicking submit, run through this checklist:

• Production build tested thoroughly

• All store assets uploaded (icon + at least one screenshot)

• Description is clear and accurate

• Permissions are justified

• Privacy policy is linked

• Extension name is descriptive

When you're ready, click "Submit for review", confirm your details, and click "Publish". Your extension enters the review queue.

Step 7: The Review Process

Google typically reviews extensions within 1–3 business days for straightforward submissions, though complex extensions or first submissions can take up to a week. Reviewers check that the extension works as described, that permissions are justified, that there's no malicious code, and that the listing complies with Chrome Web Store policies.

You can track your status in the Developer Dashboard: Pending review → In review → Approved or Rejected. If rejected, Google will email you specific reasons and instructions for resubmitting.

The most common rejection reasons are insufficient permission justification, misleading descriptions, missing privacy policies, and requesting more permissions than necessary. Address each point in the rejection email, update your submission, and resubmit.

Step 8: After Approval

Once approved, your extension is live at https://chrome.google.com/webstore/detail/[extension-id]. Share the link on social media, write a blog post, post to Reddit (r/chrome, r/chrome_extensions), or submit to Product Hunt to drive installs.

The Developer Dashboard gives you ongoing analytics — total and weekly installs, reviews and ratings, impressions, and uninstall counts. Check it regularly, especially in the first week. Respond to reviews (particularly negative ones), thank users for positive feedback, and use reported bugs to prioritize future updates.

Step 9: Publishing Updates

When you fix bugs or add features, bump the version number in package.json (following Semantic Versioning — patch for bug fixes, minor for new features, major for breaking changes), run npm run build, and upload the new package through the Developer Dashboard's Package tab. Updates are typically reviewed faster than initial submissions, often within 24 hours.

Step 10: Managing Your Extension Long-Term

The Chrome Web Store provides built-in analytics, but you can also add Google Analytics if you need more detail.

For user support, an email address in the description or a GitHub issues page both work well. As you add features, keep the description updated and maintain a changelog so users know what changed and when. Responding to user questions and reviews goes a long way toward building a loyal base of users who'll recommend the extension to others.

Troubleshooting Common Publishing Issues

"Package is invalid" on upload: Make sure you zipped the contents of build/chrome-mv3-prod/ rather than the folder itself, and verify the generated manifest.json is valid JSON.

Rejection: Permissions Not Justified: In the "Permission justification" field, be specific about which feature requires each permission and what would break without it.

Rejection: Single Purpose Unclear: Rewrite the single purpose description to focus on one main function, stated plainly.

Low installation rate after launch: Poor screenshots are often the culprit — they're the first thing most users look at. Make sure they clearly show the extension solving a real problem. Building even a small number of early reviews also makes a big difference to new visitors.

Alternative Distribution

The Chrome Web Store is the right choice for most public extensions. If you're building an internal tool, an Unlisted extension (accessible only via direct link, not searchable) is a good option.

If you need to restrict it to users in a specific Google Workspace organization, a Private extension is available for that. Self-hosting and sideloading is possible but requires users to enable Developer Mode manually, so it's only practical for very technical audiences.

Congratulations!

You've gone from an empty folder to a live Chrome extension on the Web Store. Along the way you learned how extensions are structured, how background scripts and popups communicate, how Chrome's tab APIs work, and how to navigate the publishing process end to end.

More than any specific API or configuration detail, the most important thing you've built is a mental model for how extensions work and that transfers directly to any extension idea you want to build next.

Keep building, keep learning, and keep shipping!

As projects grow and evolve, managing documentation across various formats—whether it’s markdown, HTML, or PDF for offline use—can become a time-consuming and error-prone task.

Pandoc is a powerful tool that allows you to convert documentation between formats seamlessly.

Still, even with Pandoc, manually converting files for every update can become a bottleneck in large projects or teams where documentation is frequently updated.

In this article, I’ll guide you through setting up shell scripts, using Makefiles, and integrating Pandoc into CI/CD pipelines to streamline your workflow and keep your documentation up-to-date with minimal effort.

Table of Contents

• Why Automate Documentation Conversion?

• How to Automate Pandoc using Shell Scripts

• Basic Shell Script for Pandoc Conversion

• Customizing the Script for Several Files

• Automating with Makefiles

• A Makefile for Pandoc Conversions

• Defining Dependencies in Makefiles

• Why Use Makefiles for Pandoc Automation?

• How to Integrate Pandoc with CI/CD Pipelines

• Example: Setting Up Pandoc with GitHub Actions

• Triggering on Documentation Updates

• Adapting for GitLab CI or Jenkins

• Advanced Automation Techniques

• Automating with Cron Jobs

• Ensuring Consistency with Docker

• Combining Tools for Efficiency

• Conclusion

Why Automate Documentation Conversion?

Manually converting documentation between formats in large projects can become a daunting task.

Whether you're generating HTML, PDF, or DOCX versions from the same source, repeating this process for every update leads to various challenges:

• Time-Consuming: Running manual commands to convert documentation every time you make a change eats into valuable development time when updates happen often.

• Prone to Errors: The manual process increases the likelihood of mistakes, such as using incorrect commands, missing steps, or generating outdated versions of your documentation. These inconsistencies can confuse both developers and end-users.

• Difficult to Scale: As projects grow in size, managing documents across different formats without automation can become unmanageable. Teams working in parallel may struggle to keep documentation synchronized, leading to mismatches between formats.

By automating the conversion process with tools like Pandoc, you can overcome these challenges and enjoy a range of benefits:

• Consistency: Automation ensures that all versions of your documentation are always up-to-date and accurate. No matter the number of formats you're generating, the process remains standardized.

• Efficiency: Automated workflows free up time by handling repetitive tasks in the background, allowing teams to focus on development rather than manually managing documentation updates.

• Scalability: With automation, it’s straightforward to scale documentation efforts as your project grows. Whether you're maintaining a single document or an entire library of resources, automation makes sure everything stays synchronized with minimal effort.

The next section explores how to automate the conversion process.

How to Automate Pandoc using Shell Scripts

By using shell scripts, you can streamline the process of running PanDoc commands, saving time and reducing the risk of errors associated with manual command execution.

Basic Shell Script for PanDoc Conversion

To get started, we’ll create a shell script that converts a single Markdown file into various formats.

For instance, here’s a script that converts input.md into HTML and PDF:

#!/bin/bash

# Convert input.md to HTML and PDF
pandoc input.md -o output.html
pandoc input.md -o output.pdf

echo "Conversion complete!"

In the above script:

• The #!/bin/bash line indicates that the script should be run using the Bash shell.

• The pandoc commands convert the input.md file into output.html and output.pdf.

• The echo command confirms that the conversion process is complete.

Customizing the Script for Several Files

If you want to convert all Markdown files in a directory, you can customize your script to process several files at once.

For instance, here’s a script that converts input.md into HTML and PDF:

#!/bin/bash

# Go through all the Markdown files present in the current directory
for file in *.md; do
  # Convert each Markdown file to PDF
  pandoc "$file" -o "${file%.md}.pdf"
done

echo "All conversions complete!"

In this script:

• The for loop iterates over each .md file in the current directory.

• The pandoc command converts each Markdown file to a PDF, preserving the original filename but changing the extension to .pdf with the ${file%.md}.pdf syntax.

• The final echo confirms that all conversions are complete.

Adding Error Handling and Complex Logic

To enhance your script's robustness, you can add error handling and extra logic.

For instance, perhaps you want to make sure that Pandoc is installed before proceeding, and handle cases where the input file may be missing.

The script will be as follows:

#!/bin/bash

# Check if Pandoc is installed
if ! command -v pandoc &> /dev/null; then
  echo "Pandoc is not installed. Please install it and try again."
  exit 1
fi

# Go through all the Markdown files present in the current directory
for file in *.md; do
  if [ -e "$file" ]; then
    # Convert each Markdown file to PDF
    pandoc "$file" -o "${file%.md}.pdf"
    echo "Converted $file to PDF."
  else
    echo "No Markdown files found."
  fi
done

echo "All conversions complete!"

In this enhanced script:

• The if ! command -v pandoc &> /dev/null; then line checks whether Pandoc is installed.

• The if [ -e "$file" ]; then statement checks if each Markdown file exists before attempting to convert it.

• An informative message is printed after each successful conversion, providing feedback on the process.

As your project grows in complexity, relying solely on shell scripts for automation can become difficult to manage when dealing with lots of files and frequent updates.

This is where Makefiles come in handy.

Automating with Makefiles

A Makefile is a special file that defines rules and commands for automating tasks in a project.

It’s widely used by developers to compile code, but developers can also leverage it for non-compilation tasks, such as converting documentation formats with Pandoc.

A Makefile for Pandoc Conversions

Here’s an example of how you can create a Makefile to automate Pandoc conversions:

all: html pdf

html:
    pandoc input.md -o output.html

pdf:
    pandoc input.md -o output.pdf

In this Makefile:

• all is the default target. When you run make without specifying a target, it will run the html and pdf targets sequentially.

• The html target runs a PanDoc command to convert input.md into output.html.

• The pdf target runs a PanDoc command to convert input.md into output.pdf.

To use this Makefile, run the following command in your terminal:

codemake

This will execute both the html and pdf targets, converting the Markdown file into both formats.

Defining Dependencies in Makefiles

One of the major strengths of Makefiles is their ability to handle dependencies.

In the context of documentation conversion, you can specify which files to update when you detect changes in the source file.

Let’s look at an example:

output.html: input.md
    pandoc input.md -o output.html

output.pdf: input.md
    pandoc input.md -o output.pdf

In this Makefile:

• The output.html and output.pdf files depend on input.md.

• If you run make output.html or make output.pdf, Pandoc will regenerate the corresponding file if you update input.md after the last time you created the output file.

This ensures that Pandoc converts the files that have changed, saving time when working on large documentation projects.

Why Use Makefiles for Pandoc Automation?

Makefiles offer several advantages for automating Pandoc conversions in larger projects:

• Efficiency: Makefiles rebuild what’s necessary, meaning you won’t waste time converting files that haven’t changed.

• Simplicity: Once set up, running make simplifies the conversion process to a single command, making it easier for teams to maintain consistent documentation workflows.

• Scalability: As your project grows, you can add more targets and dependencies to the Makefile, automating everything from documentation to more complex build processes.

Makefiles are an excellent option for automating documentation conversions, when combined with Pandoc for multi-format outputs.

They help ensure that your workflow is efficient and your documentation remains up-to-date.

As modern development practices increasingly rely on Continuous Integration and Continuous Deployment (CI/CD), automating routine tasks such as documentation generation becomes essential.

Integrating Pandoc into your CI/CD pipelines allows for seamless documentation conversion and updates, ensuring that your docs are always up-to-date without manual intervention.

By automating this process, you can focus on coding and building, while your pipeline handles the conversion and distribution of your project documentation. Let’s explore how to set up Pandoc in a CI/CD pipeline to streamline your documentation workflows.

How to Integrate Pandoc with CI/CD Pipelines

Automating documentation generation within your CI/CD pipeline brings significant benefits, including consistency, efficiency, and hands-off updates.

Whether you’re using GitHub Actions, GitLab CI, Jenkins, or another automation tool, integrating Pandoc ensures that documentation gets generated and distributed whenever changes occur.

This approach reduces the risk of outdated or inconsistent documentation.

Example: Setting Up Pandoc with GitHub Actions

Let’s walk through a clear example of how you can use GitHub Actions to automate the process of generating documentation with Pandoc.

Below is a basic workflow that converts a Markdown file (*.md) into a PDF whenever code gets pushed to the repository.

name: Generate Documentation

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      # Step 1: Checkout code from the repository
      - name: Checkout code
        uses: actions/checkout@v2

      # Step 2: Install Pandoc
      - name: Install Pandoc
        run: sudo apt-get install pandoc

      # Step 3: Convert Markdown to PDF
      - name: Convert Markdown to PDF
        run: pandoc input.md -o output.pdf

      # Step 4: Upload the generated PDF as an artifact
      - name: Upload Documentation
        uses: actions/upload-artifact@v2
        with:
          name: documentation
          path: output.pdf

Here’s a breakdown of each step:

• Checkout Code: The actions/checkout@v2 action retrieves the latest code from your repository.

• Install Pandoc: This step installs Pandoc on the runner (in this case, an Ubuntu machine) so that it can gets used for the documentation conversion.

• Convert Markdown to PDF: The PanDoc command converts the input.md file into output.pdf.

• Upload Documentation: This step saves the generated PDF as an artifact in the CI/CD pipeline, making it downloadable or accessible later

Triggering on Documentation Updates

You can configure your CI/CD pipeline to trigger when documentation updates occur, for example, when changes get pushed to a docs branch:

on:
  push:
    branches:
      - docs

This setup ensures that your documentation gets regenerated when changes are specifically made to the documentation branch, reducing unnecessary rebuilds.

Adapting for GitLab CI or Jenkins

While the above example uses GitHub Actions, the same principles work on other CI/CD systems like GitLab CI or Jenkins.

For instance, in GitLab CI, you could define a .gitlab-ci.yml file that follows similar steps to check out the code, install Pandoc, convert the files, and store the resulting documentation.

Integrating Pandoc into your CI/CD pipeline offers a reliable way to automate your documentation workflows, ensuring that your project docs are always current, accurate, and accessible.

Advanced Automation Techniques

When your project reaches a stage where documentation needs to be generated frequently or across multiple environments, it’s essential to extend your automation strategy to maintain consistency and reliability.

Automating with Cron Jobs

For projects where documentation updates occur frequently, but not always due to code pushes or commits, you can automate the process using cron jobs.

Cron allows you to schedule tasks at specific intervals, meaning your documentation can automatically get updated at set times without needing manual input.

For example, setting up a cron job to run every day at midnight to convert Markdown files to PDFs:

0 0 * * * /path/to/pandoc /path/to/input.md -o /path/to/output.pdf

With this cron job in place, Pandoc will automatically convert your Markdown files to PDFs at the specified time, ensuring that your documentation remains up-to-date without manual intervention.

Ensuring Consistency with Docker

When working in a team or across various systems, ensuring that Pandoc runs consistently in different environments can be challenging.

Docker provides a solution to this by allowing you to package Pandoc and all its dependencies in a container, ensuring that the same setup gets used everywhere.

This is useful in CI/CD pipelines, where different environments (like local machines, staging, and production servers) can have different configurations.

You can use the official Pandoc Docker image to simplify the setup process:

docker run --rm -v $(pwd):/data pandoc/core:latest input.md -o output.pdf

This command runs Pandoc inside a Docker container, using the latest version of Pandoc, and mounts your current directory to the container’s /data directory.

By doing this, you ensure that no matter where the pipeline runs, the conversion will work the same way every time.

Combining Tools for Efficiency

By combining tools like cron jobs and Docker, you can set up an advanced automation pipeline that ensures:

• Scheduled updates: Cron jobs trigger documentation generation at regular intervals.

• Consistency across environments: Docker ensures that Pandoc and its dependencies are the same on every machine.

• Reliability: Together, these tools help ensure that your documentation is always accurate, no matter where or when it’s generated.

These advanced techniques allow you to further streamline your documentation workflows, improving both efficiency and reliability as your project grows.

Conclusion

Automating documentation conversion with Pandoc not only saves time but also ensures consistency and scalability as your project grows.

Whether you’re managing small or large projects, these techniques enable you to focus on coding and building, knowing that your documentation is automatically up-to-date and ready for distribution.

By embracing automation, you streamline your development process and enhance collaboration across teams, ensuring that your documentation evolves as efficiently as your code.

Now it’s time to apply these tools to your projects and enjoy the benefits of a fully automated documentation pipeline.

Let’s stay in touch:

• Connect with me on LinkedIn. I post regularly, so following me is a great idea.

• Follow me on X

Feel free to reach out through the channels above if you have any questions. I will be happy to help.

Developers rely on tools like compilers and bundlers to transform their code, optimize performance, and ensure compatibility across different environments.

These tools are essential for modern JavaScript applications, enabling developers to write clean, maintainable code while leveraging the latest language features.

This article will help you understand what Speedy Web Compiler (SWC) is and how it helps optimize the performance of your web apps.

Table of Contents

• Introduction to Speedy Web Compiler

• Background of SWC

• How Speedy Web Compiler Works

• Benefits of Using Speedy Web Compiler

• How to Set Up Speedy Web Compiler in Your Project

• SWC Integration in Popular Frameworks

• Conclusion

What is Speedy Web Compiler?

First, let me break it down.

SWC stands for Speedy Web Compiler, and when broken down:

Speedy - This means it's fast! SWC processes and transforms JavaScript code, making it efficient to use in big projects.

Web - It’s all about web development. It focuses on improving how JavaScript (the language of the web) handles it.

Compiler - It takes code written in one form and transforms it into another form that can be better understood or used by computers.

Background of SWC

kdy1, a South Korean developer and maintainer of Next.js, created SWC as a faster tool for handling JavaScript code.

The motivation was the need for speed and efficiency, as web projects grow larger and more complex.

With numerous websites and apps depending on JavaScript, SWC helps developers save time and work more efficiently.

How Speedy Web Compiler Works

SWC uses Rust, a programming language known for its speed and safety.

SWC works by taking your JavaScript or TypeScript code and transforming it into a version that can run efficiently in various environments.

Understanding how SWC achieves this involves examining its core steps: parsing, transforming, and generating code.

How Does SWC Parse Code?

The first step in the compilation process is parsing.

Begins by reading and analyzing the code to understand its structure.

This is akin to taking a complex sentence and breaking it down into its grammatical components—subject, verb, object, etc.

In technical terms, SWC converts your code into an Abstract Syntax Tree (AST).

The AST is a tree-like representation of the source code, where each node in the tree corresponds to a construct occurring in the code, such as expressions, statements, and functions.

This tree structure allows SWC to process and understand the code’s logic in a way that is both efficient and scalable.

How Does SWC Transform Code?

After creating the AST, SWC moves on to the transformation phase.

This is where the magic happens—SWC applies various optimizations and changes to the code based on the target environment.

For instance, if you're targeting older browsers that don't support modern JavaScript features, SWC will transform your ES6+ code into a backward-compatible version.

During this phase, SWC also handles TypeScript transformations. It strips away TypeScript-specific syntax, such as types and interfaces, converting the code into pure JavaScript that gets executed by any JavaScript engine.

SWC can apply custom transformations based on plugins or specific configurations, making it highly versatile.

How Does SWC Generate Optimized Code?

After the transformations are complete, SWC proceeds to the final step: code generation.

In this step, SWC takes the transformed AST and converts it back into executable code.

In contrast, this process is not just a reversal of the parsing process.

SWC takes special care to generate code that is both functionally correct and optimized for performance.

For instance, SWC might remove dead code (code that will never be executed) or inline certain functions to reduce overhead.

The goal is to produce code that is as clean and efficient as possible, ensuring that it runs quickly and reliably in production environments.

Benefits of Using Speedy Web Compiler

Performance

One of the major benefits of using SWC is its outstanding speed. SWC achieves this exceptional speed by using Rust.

Developers can expect a significant performance improvement when compiling their code for large projects or codebases.

This speed greatly reduces build times, enhancing the efficiency and responsiveness of the development process. It is so fast, you might think it’s late for a meeting!

Optimized Output

SWC compiles your code and guarantees that the output is highly optimized for performance in production environment by removing dead code, in-lining functions, and reducing the size of the output.

This makes using SWC cost-effective, saving you from extra expenses during production.

The result is a leaner, faster, and more efficient code that can enhance loading times and performance in web applications.

Compatibility

SWC is fully compatible with modern JavaScript libraries and frameworks.

You do not have to worry about using ES6+ or TypeScript. This makes SWC a versatile choice for your projects.

How to Set Up Speedy Web Compiler

Installation

To install SWC in your JavaScript or TypeScript project, follow these steps:

1. Initialize your project: If you haven't already, start by initializing a new project. In your terminal, run:

npm init -y

2. Install SWC with npm: Run the following command to download the pre-built binaries:

npm install -D @swc/cli @swc/core

3. Create a JavaScript file: Create a src/index.js file with some code:

const greet = (name) => {
  return `Hello, ${name}!`;
};

console.log(greet("World"));

4. Compile with SWC: Run SWC from the command line to compile your JavaScript file:

npx swc src/index.js -o dist/index.js

5. Resulting Code: The resulting JavaScript code in dist/index.js will look like this:

"use strict";
var greet = function(name) {
    return "Hello, " + name + "!";
};
console.log(greet("World"));

This is the transpiled ES5 code produced by SWC, suitable for environments that require backward compatibility with older JavaScript versions.

SWC Integration in Popular Frameworks

If you are using Next.js, Deno, Vite, Remix, Parcel, or Turbopack, SWC is already integrated.

Notable improvements were made on Next.js, a popular React framework, since version 12 (Source: Next.js 12: The SDK for the Web)

Conclusion

In the constantly changing realm of JavaScript development, having the correct tools can make a significant difference.

SWC, the Speedy Web Compiler, distinguishes itself as a strong solution for converting and optimizing JavaScript and TypeScript code.

Its impressive speed, owing to its Rust-based implementation, along with its efficient management of code transformations and optimizations, positions it as a powerful tool for modern web development.

If you would like to stay in touch:

Connect with me on LinkedIn

Follow me on X