Lessons Learned Shipping My First OSS Project with Next.js + shadcn

Ayberk — Thu, 31 Jul 2025 20:04:45 +0000

Last day I shipped Duelr v0.1.1, a one-click LLM comparison tool that lets you see which LLM, such as GPT-4o, Claude 4 Sonnet, Groq etc., performs best for your own prompt, not a generic benchmark.

I wanted to document what worked (and what very much didn’t) during my first open-source journey. If you’re about to launch your own OSS project, I hope these notes save you a few headaches.

Repo: Duelr (Apache-2.0 license, contributions welcome!)

1. Project Snapshot

Area	Details
Frontend / Runtime	Next.js, shadcn/ui, TypeScript
Backend	None—Next.js server routes call third-party LLM APIs directly
CI / CD	GitHub Actions
Linting	ESLint, Prettier

2. Docs Before Dopamine

I forced myself to finish the boring artifacts before polishing UI:

README – Short “Why / Try / How” structure; everything still fits on one screen.
GitHub Issue Forms – YAML-based forms, not Markdown templates, so every bug report arrives pre-structured.
CONTRIBUTING – Quick-start, branch flow, Conventional Commits cheat-sheet.
LICENSE (Apache-2.0) & CODE_OF_CONDUCT

Tip: If you use Issue Forms, remember to set default labels in the YAML; otherwise issues arrive unlabeled.
Tip: Don't forget to create some issue labels since GitHub defaults are terrible. They say "enhancement" for new feature requests. New feature is new feature. Enhancement/improvement/refactoring is to develop something further to make it better.

3. The Boss Fight: Automated Releases

I wanted semantic versioning plus autogenerated changelogs and releases, so I picked Google’s release-please Action. The promise:

Parse Conventional Commits (feat:, fix:, BREAKING: …).
Open a “chore: release vX.Y.Z” PR.
On merge, tag and publish the release + changelog.

The Gotcha

release-please reads either the Action inputs or a repo-level config file, not both. Once you add release-please-config.json, any parameters in your workflow YAML are ignored. I spent a night wondering why my configs were not applied.

Working Minimal Setup

{
  "packages": {
    ".": {
      "release-type": "node",
      "changelog-sections": [
        { "type": "feat", "section": "✨ Features" },
        { "type": "fix", "section": "🐛 Bug Fixes" },
        { "type": "perf", "section": "⚡ Performance Improvements" },
        { "type": "docs", "section": "📚 Documentation" },
        { "type": "style", "section": "💄 Styles" },
        { "type": "refactor", "section": "♻️ Code Refactoring" },
        { "type": "test", "section": "✅ Tests" },
        { "type": "build", "section": "🔧 Build System" },
        { "type": "ci", "section": "👷 CI/CD" },
        { "type": "revert", "section": "⏪ Reverts" }
      ],
      "bump-minor-pre-major": true,
      "bump-patch-for-minor-pre-major": false,
      "draft": false,
      "prerelease": false,
      "skip-github-release": false,
      "include-component-in-tag": false
    }
  }
}

name: Release

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      ...

      - name: Release
        uses: google-github-actions/release-please-action@v4
        id: release
        with:
          token: ${{ secrets.RELEASE_TOKEN }}
          config-file: release-please-config.json
          manifest-file: .release-please-manifest.json

Now every merge to main bumps SemVer, updates CHANGELOG.md, and cuts a GitHub release in seconds.

4. Did I Miss Any Best Practices?

This is my first OSS journey, so I’m sure I broke a convention or two.
How would you improve the workflow or project layout? I’d love your feedback and, of course, PRs are very welcome!

👉 Repo: Duelr

Thanks for reading, and good luck on your own open-source adventures!