projkit

projkit

Git commit workflow CLI for Node.js projects.

Features

• Commit message template with conventional format
• Auto-detect package scope from staged files (monorepo support)
• Auto-extract issue number from branch name
• Version management with package@version tags
• Release Please setup for automated changelog generation
• Multi-language support (English, Korean)
• Custom template path support

Installation

npm install -D projkit
# or
pnpm add -D projkit
# or
yarn add -D projkit

Installation automatically configures:

• Git commit template
• Git hooks (prepare-commit-msg)
• Default editor settings

Note: Interactive prompts are skipped during install to avoid blocking CI/CD. Run npx projkit --setup to customize settings.

Commands

npx projkit [command] [options]

Command	Description
(default)	Run setup (non-interactive)
--setup	Run interactive setup
version <type>	Bump version and create git tag
doctor	Check project configuration status
guide [topic]	Show workflow guides
help	Show help message

Options

Option	Description
-y, --non-interactive	Skip all prompts, use defaults

Usage

Setup

# Interactive setup
npx projkit --setup

# Quick setup with defaults
npx projkit -y

Configurable options:

• Git editor (VS Code, Cursor, Nano, Vim)
• Language (English, Korean)
• Commit template (default or custom path)
• Release Please (auto changelog & release)

Version Management

Bump package version with automatic git tag in package@version format.

cd src/packages/my-package
npx projkit version <type>

Type	Example
patch	0.0.1 → 0.0.2
minor	0.0.1 → 0.1.0
major	0.0.1 → 1.0.0
x.y.z	Set specific version

$ npx projkit version patch

Bumping my-package: 0.0.1 → 0.0.2
  ✓ Updated package.json
  ✓ Created commit: chore(my-package): release 0.0.2
  ✓ Created tag: my-package@0.0.2

To push changes:
  git push && git push origin my-package@0.0.2

Doctor (Configuration Check)

Check if your project is properly configured.

npx projkit doctor

Checks:

Check	Description
Git Hook	Is projkit hook configured?
Commit Template	Is commit template set?
Release Please	Is release-please configured? (optional)
Version Sync	Are manifest and package.json versions in sync?

Example output:

🔍 Checking project...

✅ Git Hook is configured correctly.
✅ Commit template is configured.
✅ Release Please is configured.
✅ Versions are in sync. (.)

💡 Tips:
⚠️  Do not change version manually when publishing!
   Use the version managed by release-please as-is.
📖 More info: npx projkit guide publish

✨ All settings are correct!

Guide (Workflow Documentation)

Show workflow guides for common tasks.

npx projkit guide [topic]

Available topics:

Topic	Description
publish	How to publish without breaking version sync
release-please	How release-please workflow works
commit	Commit message format guide

Example:

# Show available topics
npx projkit guide

# Show publish workflow guide
npx projkit guide publish

# Show release-please guide
npx projkit guide release-please

# Show commit format guide
npx projkit guide commit

Publish workflow guide preview:

📦 Publish Workflow Guide

❌ Wrong way:
  ┌─────────────────────────────────────────────┐
  │ 1. feat commit → merge to main              │
  │ 2. npm version patch  ← manual version      │
  │ 3. npm publish                              │
  │ → Out of sync with release-please!          │
  └─────────────────────────────────────────────┘

✅ Correct way:
  ┌─────────────────────────────────────────────┐
  │ 1. feat commit → merge to main              │
  │ 2. Merge release-please PR  ← auto version  │
  │ 3. npm publish (no version change)          │
  │ → Stays in sync!                            │
  └─────────────────────────────────────────────┘

💡 Key: Don't touch version during publish, it stays in sync.

Release Please Setup

Set up automated changelog generation and release management with release-please.

npx projkit --setup
# At step [7/7], select "Yes" for Release Please setup

What Gets Created

File	Description
.github/workflows/release-please.yml	GitHub Action workflow
release-please-config.json	Release configuration
.release-please-manifest.json	Version manifest

Workflow Scenario

┌─────────────────────────────────────────────────────────────────┐
│  1. DEVELOP                                                      │
│     Write code and commit with conventional format              │
│     $ git commit -m "feat(auth): add OAuth login"               │
│     $ git commit -m "fix(core): resolve memory leak"            │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  2. MERGE TO MAIN                                                │
│     Create PR and merge to main branch                          │
│     Release Please Action triggers automatically                │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  3. RELEASE PR (Auto-generated)                                  │
│     Release Please creates/updates a Release PR:                │
│     - Version bump in package.json                              │
│     - CHANGELOG.md updated with all changes                     │
│     - PR title: "chore(main): release my-package 1.2.0"         │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  4. REVIEW & EDIT (Optional)                                     │
│     - Review the generated CHANGELOG.md                         │
│     - Edit descriptions if needed                               │
│     - Add additional notes                                      │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  5. MERGE RELEASE PR                                             │
│     When ready, merge the Release PR:                           │
│     - GitHub Release created automatically                      │
│     - Git tag created (e.g., v1.2.0)                            │
│     - npm publish triggered (if configured)                     │
└─────────────────────────────────────────────────────────────────┘

Generated CHANGELOG Example

# Changelog

## [1.2.0](https://github.com/org/repo/compare/v1.1.0...v1.2.0) (2024-01-15)

### Features

* **auth:** add OAuth login support ([#42](https://github.com/org/repo/issues/42))
* **api:** implement rate limiting ([#45](https://github.com/org/repo/issues/45))

### Bug Fixes

* **core:** resolve memory leak in cache ([#43](https://github.com/org/repo/issues/43))
* **ui:** fix button alignment ([#44](https://github.com/org/repo/issues/44))

Version Bump Rules

Commit Prefix	Version Bump	Example
fix:	Patch	1.0.0 → 1.0.1
feat:	Minor	1.0.0 → 1.1.0
feat!: or BREAKING CHANGE:	Major	1.0.0 → 2.0.0

Monorepo Support

For monorepo projects, projkit automatically:

• Detects pnpm-workspace.yaml, lerna.json, or workspaces in package.json
• Finds packages in packages/, src/packages/, apps/, libs/
• Generates separate changelog for each package

# Generated release-please-config.json for monorepo
{
  "packages": {
    "src/packages/auth": { "package-name": "@myorg/auth", ... },
    "src/packages/core": { "package-name": "@myorg/core", ... }
  }
}

Manual Changelog Edit

You can always edit CHANGELOG.md manually:

• Before merging Release PR: Edit directly in the PR
• After release: Edit CHANGELOG.md and commit normally
• Custom sections: Add sections like "Migration Guide", "Known Issues"

Commit Workflow

Standard commit (with template)

git commit

Opens your editor with the commit template.

Quick commit

git commit -m "feat: your message"

You'll be prompted:

• y) Proceed as-is
• t) Open template editor
• c) Cancel

Auto Features (Monorepo)

Package Scope Detection

Automatically detects changed packages from src/packages/*/:

# Files in src/packages/auth/ staged
git commit -m "feat: add login"
# → feat(auth): add login

# Multiple packages
# → feat(auth, core): add login

Issue Number Extraction

Extracts issue number from branch name:

# Branch: feature/123-add-login
git commit -m "feat: add login"

# Result:
# feat: add login
#
# Closes #123

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Types

Type	Description
feat	New feature
fix	Bug fix
docs	Documentation
style	Formatting (no logic change)
refactor	Code refactoring
perf	Performance improvement
test	Tests
build	Build system
deps	Dependencies
ci	CI configuration
chore	Other changes
revert	Revert commit

Example

feat(auth): add OAuth2 login support

- Add Google OAuth2 provider
- Add callback handler for OAuth flow
- Store refresh token securely

Closes #42

Configuration

After setup, .commitrc.js is generated:

export default {
  language: 'en',
  editor: 'code --wait',
  templatePath: './node_modules/projkit/templates/commit-template.en.txt',
  hooksPath: './node_modules/projkit/hooks',
}

Custom Template

npx projkit --setup
# Select "Use custom template path"
# Enter: ./my-commit-template.txt

Development

# Enable corepack (once per machine, enforces pnpm version)
corepack enable

# Install dependencies
pnpm install

# Build
pnpm build

# Watch mode (build)
pnpm dev

# Type check
pnpm typecheck

# Run tests
pnpm test

# Watch mode (test)
pnpm test:watch

Scripts

Script	Description
pnpm build	Build TypeScript
pnpm dev	Build in watch mode
pnpm typecheck	Type check
pnpm test	Run tests
pnpm test:watch	Run tests in watch mode
prepublishOnly	Build + test before publish

CI/CD

GitHub Actions runs tests on:

• Push to main (projkit changes)
• Pull requests to main (projkit changes)

Test matrix: Node.js 18, 20, 22

Release Workflow

This project uses release-please for automated versioning and changelog generation.

How it works

• Develop: Create commits with Conventional Commits format

  git commit -m "feat(projkit): add new feature"
  git commit -m "fix(projkit): resolve bug"
  

• Auto Release PR: When commits are merged to main, release-please automatically creates/updates a Release PR with:

  • Version bump in package.json
  • Generated CHANGELOG.md

• Release: When ready, merge the Release PR

  • GitHub Release is created automatically
  • npm publish is triggered automatically

Version Bump Rules

Commit Type	Version Bump	Example
fix:	patch	1.0.0 → 1.0.1
feat:	minor	1.0.0 → 1.1.0
feat!: or BREAKING CHANGE:	major	1.0.0 → 2.0.0

Manual Publish (Optional)

For manual publishing (e.g., dry run testing):

• Go to Actions → Projkit Publish
• Click Run workflow
• Enable Dry run to test without publishing
• Click Run workflow

Note: Uses npm Trusted Publisher (OIDC). No token required.

Requirements

• Node.js >= 18.0.0
• Git
• Bash (macOS, Linux, Windows with Git Bash/WSL)

License

MIT