code-divider

code-divider turns simple comment markers into tidy, centered region/section dividers. No counting = signs. No lining things up by hand.

Use it from the command line, run it automatically when you save, or call it from your own code.

👀 Preview

🧭 Table of contents

• 👀 Preview
• 🚀 Quick start
• 📌 Markers
• 💻 Command-line options
• 💾 Run on save
• 🧩 Divider anatomy
• 🔧 Configuration
  • Create a config file
  • How config files are found
  • Shared settings
  • Language-specific settings
  • Built-in languages
  • Filtering files
• 💻 Programmatic use
• 📄 License

🚀 Quick start

Add a marker on its own line in a source file:

// @reg utilities

// @sec helper functions

Then run (inside of your project folder):

npx code-divider

Your markers are replaced in place with formatted headers. That’s it!

You can target a file or a folder. Folders are searched recursively.

npx code-divider --path ./src --dry-run

📌 Markers

There are two kinds of dividers:

Use your language’s comment syntax:

// @sec helper functions

# @sec helper functions

/* @sec helper functions */

By default, region labels become UPPERCASE and section labels become Capitalized Words. You can customize both in Configuration.

Built-in support includes JavaScript, TypeScript, Java, CSS, SCSS, C, C++, Go, Rust, PHP, Ruby, Python, Bash, and SQL. You can add more languages through the configuration file.

💻 Command-line options

npx code-divider [options]

With no options, code-divider processes the current directory.

A few examples:

# Process the current directory
npx code-divider

# Process one file
npx code-divider --path ./src/index.ts

# Check for changes in CI without modifying files
npx code-divider --check

# Use a specific config file
npx code-divider --config ./custom.config.json

💾 Run on save

This is my favorite way to use code-divider: write a marker, hit save, and let your editor handle the rest.

If your editor supports running commands on save, configure it to run npx code-divider.

For VS Code, install the Run on Save extension and add this setting to your settings.json:

{
  "emeraldwalk.runonsave": {
    "commands": [
      {
        "match": "\\.(css|js|jsx|ts|tsx)$",
        "cmd": "npx code-divider"
      }
    ]
  }
}

🧩 Divider anatomy

Here’s a section divider, shortened for readability:

// ============== My Section ============== //

These are the names used throughout the configuration:

🔧 Configuration

The defaults work out of the box. Add a config file only when you want to make the dividers your own.

Create a config file

Start with a file containing all the default settings:

npx code-divider --init

This creates code-divider.config.json in the current directory. It won’t overwrite an existing file.

To create it somewhere else:

npx code-divider --init ./packages/app

How config files are found

Unless you pass --config <file>, code-divider checks locations in this order:

1. The target directory, or the containing directory if the target is a file.
2. The directory the command is run from.

The first config file found wins. These config files are not merged together.

Settings in the selected config file override the built-in defaults. Anything you leave out keeps its default value. If no config is found, the built-in defaults are used.

Shared settings

The All key contains settings shared by every language:

Both label-format settings accept:

Words that start or end with a non-alphanumeric character are left unchanged under every format. That keeps labels containing things like @decorator or .foo intact.

Language-specific settings

Other than All and filter, top-level config keys can be any string value, they're just there for organization. You can use a built-in key to customize that language's current settings, or a new key to add your own.

For example:

{
  "All": {
    "CharacterLimit": 100,
    "FillerCharacter": "-"
  },
  "Java": {
    "Bookends": ["// ", " //"]
  },
  "Python": {
    "Extensions": ["py"],
    "Comment": ["# ", ""]
  }
}

// Main.java
class Main {

    // ===================================================================== //
    //                               FUNCTIONS                               //
    // ===================================================================== //

    public static void main(String[] args) {
        System.out.println("Hello code-dividers");
    }
}

# Main.python

# =========================================================================== #
#                                  CONSTANTS                                  #
# =========================================================================== #

print('Hello code-divider')

Default Settings

These are the language keys, file extensions, and comment styles available by default.

Filtering files

Use the top-level filter key to choose which files get processed.

Patterns work like include and exclude in a tsconfig.json. They are relative to the folder being processed.

Filters select the files to consider, but to be updated those files still need to match a configured language extension.

In case you're wondering why I didn't use Node's built-in fs.glob function, it's only available in Node 22+ and marked experimental until Node 24.

Default exclusions

Out of the box, code-divider skips:

• At any depth: node_modules, .vscode, .idea, .claude, and files ending in .log or .json.
• At the top level: bin, lib, and dist.

💻 Programmatic use

import { insertCodeDividers } from 'code-divider';

const updatedFiles = await insertCodeDividers('targetPath', options?)

targetPath can be a file or directory. Relative paths are resolved against options.cwd.

All options are optional:

The logger receives:

• info messages, such as which config file is being used.
• warn messages, such as a marker with no label.

📄 License

MIT © seanpmaxwell