DEV Community

Dharam Ghevariya
Dharam Ghevariya

Posted on

Adding TOML Config File Support to an Open Source CLI Project

#opensource #cli #tooling #learning

In Week 5 of my Open Source Development course, the task was to add a new feature to another student’s repository. I decided to work on the project Repository-Context-Packager. This tool helps package useful information about a repository so it can be used later.

The Problem

Right now, to run the tool you need to type a long command every time. For example:

repo-packager "PATH/TO/REPO" \
  --output "output.txt" \
  --include "*.js" \
  --exclude "*test*" \
  --max-file-size 1024 \
  --format "json"
Enter fullscreen mode Exit fullscreen mode

If you always use the same options, typing this again and again is not very user-friendly.

The Solution: TOML Config File

To fix this, I added support for a TOML config file. This means you can create a simple file called .repo-packager-config.toml in your project folder:

output = "output.txt"
include = "*.js"
exclude = "*test*"
max_file_size = 1024
format = "json"
Enter fullscreen mode Exit fullscreen mode

Now, the tool will read these values automatically. You don’t need to type them in the command line each time.

How I Built It

To handle TOML files, I chose smol-toml, a lightweight library that is simple and straightforward to work with.

Here’s the main function I wrote:

export function loadConfig() {
  const configFileName = ".repo-packager-config.toml";
  const configPath = path.join(process.cwd(), configFileName);

  // If config file doesn't exist, return empty config
  if (!fs.existsSync(configPath)) {
    return {};
  }

  try {
    const configContent = fs.readFileSync(configPath, "utf-8");
    const config = parseToml(configContent);
    return config;
  } catch (error) {
    console.error(
      `Error parsing TOML config file '${configFileName}': ${error.message}`
    );
    process.exit(1);
  }
}
Enter fullscreen mode Exit fullscreen mode

This function first checks if the config file exists in the current directory. If it does, it opens the file, reads the contents, and parses it into an object so the program can use the values as options. If the file does not exist, it simply returns an empty object.

Working With the Maintainer

Before I began coding, I opened an issue in the repository to explain my feature idea and to get the maintainer’s feedback. This step was important because it made sure the idea was useful and aligned with the project. After the maintainer approved the idea, I created a draft pull request. A draft PR is useful because it lets others see that you are actively working on the feature, even if it’s not finished yet. Once I completed the feature, tested it, and updated the README with instructions, I changed the pull request from draft to ready for review. This signaled to the maintainer that the work was complete and ready to be checked. The full changes can be seen in Pull Request #16.

Reviewing the Same Feature in My Repo

Now the roles were reversed, I was the maintainer and got the feature contribution. One of my classmates suggested the same feature in my own project, repo-contextr, and opened PR #16.

To properly test their changes, I first added their fork of my repository as a new remote:

git remote add bhchen24 https://github.com/BHChen24/repo-contextr.git
Enter fullscreen mode Exit fullscreen mode

This gave me access to their version of the repository. Next, I checked out the branch they had created for the feature:

git checkout -b issue-15-feat-support-using-a-TOML-dotfile-config-file bhchen24/issue-15-feat-support-using-a-TOML-dotfile-config-file
Enter fullscreen mode Exit fullscreen mode

By doing this, I created a local branch that pointed directly to their work. This allowed me to pull down their changes and run the code on my own machine. Running it locally was important so I could confirm that the new TOML config feature worked as expected.

During my review, I noticed a few issues where the implementation didn’t fully meet the requirements. I started a review on GitHub, added comments, and opened a discussion thread with my feedback (review link)[https://github.com/dharamghevariya/repo-contextr/pull/16#pullrequestreview-3291624639]. The contributor then made the necessary fixes and pushed the updates to their branch.

Once I confirmed the fixes worked, I merged the changes into the main branch of my project with the following steps:

git checkout main
git merge issue-15-feat-support-using-a-TOML-dotfile-config-file
git push origin main
Enter fullscreen mode Exit fullscreen mode

After pushing to GitHub, the pull request was automatically marked as merged. This completed the process and added the new feature into my project.

Learnings

This week’s task helped me learn both sides of open source work:

  • As a contributor: suggest a feature, open a PR, and finish it with tests and docs.
  • As a maintainer: review someone else’s PR, give feedback, and merge changes.

It showed me the value of good communication, small steps (using draft PRs), and always testing code locally before merging.

Top comments (0)