nextjs-pr-workflow

name	nextjs-pr-workflow
description	Next.js PR workflow with quality checks (lint/build/test), semantic versioning labels (major/minor/patch), coverage badges, and JIRA integration via pr-creation-workflow framework Use when this capability is needed.
metadata	{"author":"darellchua2"}

What I do

I implement a complete Next.js PR creation workflow by extending framework skills:

1. Identify Target Branch: Determine which branch PR should merge into (configurable, not hardcoded)
2. Run Next.js Quality Checks: Execute npm run lint, npm run build, and npm run test using linting-workflow framework
3. Identify Tracking: Check for JIRA tickets or git issue references
4. Create Pull Request: Use pr-creation-workflow framework with git-semantic-commits for PR title formatting
5. Add JIRA Comments: Use git-issue-updater framework for consistent JIRA ticket updates

Critical Requirement: All tests MUST pass (npm run test) before PR creation. This is a blocking step.

When to use me

Use this workflow when:

• Completing implementation of a PLAN.md file
• Finishing new feature implementation in Next.js apps
• Ready to create a PR after development is complete
• Need to ensure code quality before submitting changes
• Following the standard practice of linting, building, and testing before PR
• All tests must pass before PR can be created (blocking requirement)

Frameworks Used:

• pr-creation-workflow: For PR creation logic and quality checks
• linting-workflow: For Next.js linting (npm run lint)
• jira-git-integration: For JIRA ticket management and comments

Prerequisites

• Next.js project with npm run lint, npm run build, and npm run test scripts
• Git repository initialized and on a feature branch
• Active Atlassian/JIRA account (if using JIRA integration)
• Write access to repository
• PLAN.md file with implementation details
• All existing tests must pass before using this workflow

Steps

Step 1: Check Project Structure

Verify this is a Next.js project and check for required scripts:

# Verify package.json exists and has required scripts
jq -r '.scripts.lint and .scripts.build and .scripts.test' package.json

Required scripts: lint, build, and test. If any script is missing, the workflow cannot proceed.

Step 2: Identify Target Branch

Ask user which branch PR should merge into. Note: This is not necessarily dev - different projects use different conventions.

Use: Ask user or detect default from git symbolic-ref

Step 3: Run Quality Checks via Linting Workflow

Use linting-workflow framework with JavaScript/TypeScript language detection:

• Framework: ESLint
• Package manager: npm/yarn/pnpm
• Run npm run lint (or yarn lint / pnpm lint)
• Apply auto-fix with npm run lint -- --fix
• Handle errors with re-running

Step 4: Run Tests (BLOCKING STEP)

Before proceeding to PR creation, all tests must pass:

# Run test suite
npm run test

# Or with coverage
npm run test -- --coverage

Behavior:

• If tests pass: Continue to PR creation
• If tests fail: Do NOT create PR. User must fix failing tests first
• Error message: "Tests failed. Please fix test failures before creating PR. Run: npm run test"

Test Requirements:

• All unit tests must pass
• All integration tests must pass
• No skipped tests (unless documented)
• Coverage threshold (if configured) must be met

Step 5: Update Coverage Badge in README

Use coverage-readme-workflow to update README with latest coverage:

• Run tests with coverage
• Extract coverage percentage
• Update coverage badge in README.md
• Ensure badge color reflects coverage level

This ensures PR includes updated coverage documentation.

Coverage Update Command:

# Run coverage workflow (delegated to coverage-readme-workflow)
opencode --agent coverage-readme-workflow "update coverage badge"

Behavior:

• If coverage badge exists: Update with new percentage
• If coverage badge doesn't exist: Add new badge and section
• Badge color reflects coverage level (>=80% green, 60-79% yellow, 40-59% orange, <40% red)

Step 6: Identify Tracking System

Read PLAN.md for JIRA ticket references:

# Check for JIRA ticket
PLAN_JIRA=$(grep -oE "[A-Z]+-[0-9]+" PLAN.md | head -1)

Step 7: Create Pull Request via PR Workflow

Use pr-creation-workflow framework with Next.js-specific configuration:

• Quality checks: npm run lint, npm run build, and npm run test
• Test validation is MANDATORY - PR cannot be created if tests fail
• Target branch: User-specified or detected
• Tracking: JIRA ticket or git issue
• Platform: GitHub PR (not GitLab)
• Use git-semantic-commits for PR title formatting: Follow Conventional Commits specification
  • Examples: feat: add user authentication, fix(ui): resolve layout issue, docs: update API docs
  • Include ticket reference: feat: add login feature [IBIS-456] or fix(IBIS-456): resolve session timeout
  • Use scope: feat(api): add authentication, fix(ui): resolve layout issue
  • Breaking changes: feat!: breaking API change or feat(api)!: breaking change to authentication
• PR body should include test results summary
• Apply semantic versioning label automatically:
  • feat! → major label (breaking change)
  • feat → minor label (new feature)
  • fix → patch label (bug fix)

Step 8: Apply Semantic Versioning Label

After PR creation, apply the appropriate version label:

# Get PR number
PR_NUMBER=$(gh pr list --head "$(git branch --show-current)" --json number --jq '.[0].number')

# Detect and apply label based on PR title
PR_TITLE=$(gh pr view "$PR_NUMBER" --json title --jq '.title')

if [[ "$PR_TITLE" =~ ^[^:]+\! ]]; then
  gh pr edit "$PR_NUMBER" --add-label "major"
elif [[ "$PR_TITLE" =~ ^feat ]]; then
  gh pr edit "$PR_NUMBER" --add-label "minor"
elif [[ "$PR_TITLE" =~ ^fix ]]; then
  gh pr edit "$PR_NUMBER" --add-label "patch"
else
  gh pr edit "$PR_NUMBER" --add-label "patch"
fi

Step 9: Handle JIRA Integration via Git Issue Updater

Use git-issue-updater framework for:

• JIRA resource detection (cloud ID, projects)
• Adding comments with PR details (user, date, time, commit hash, files changed)
• Uploading images (if applicable)
• Consistent progress tracking across all JIRA tickets

Step 10: Merge Confirmation

After PR creation, ask user to confirm merge target before proceeding.

Example PLAN.md Integration

When your PLAN.md contains:

# Plan: Add New Feature

## Overview
Implements a new feature for...

## JIRA Reference
IBIS-456: https://company.atlassian.net/browse/IBIS-456

## Implementation
...

This skill will:

1. Detect JIRA ticket IBIS-456
2. Run linting and build
3. Create PR with Conventional Commits format (e.g., feat: add user component [IBIS-456])
4. Add comment to JIRA ticket IBIS-456 using git-issue-updater
5. Prompt for merge target

Common Issues

Linting Errors

• Issue: Many linting errors at once
• Solution: Run npm run lint -- --fix first, then manually fix remaining errors

Build Failures

• Type Errors: Check TypeScript types and interfaces
• Import Errors: Verify all imports are correct and paths exist
• Missing Dependencies: Run npm install to ensure all dependencies are installed
• Environment Variables: Check .env.local or environment configuration

JIRA Integration

• Permission Denied: Ensure your account has JIRA access and comment permissions
• Cloud ID Not Found: Use atlassian_getAccessibleAtlassianResources to locate it
• Ticket Not Found: Verify the ticket key exists and is accessible

Git Issues

• Branch Diverged: Rebase with git rebase <target-branch> before PR creation
• Wrong Target Branch: Verify you're creating the PR against the correct branch (not always dev)
• Unstaged Changes: Ensure all changes are committed before PR
• No gh CLI: Install GitHub CLI: https://cli.github.com/

Best Practices

• Always run linting, building, and testing before creating any PR
• Never create a PR with failing tests - this is a blocking requirement
• Keep PRs focused and small (ideally < 400 lines changed)
• Use git-semantic-commits for PR title formatting following Conventional Commits specification
• Write clear, descriptive PR titles: feat: add user component [IBIS-456] or fix(IBIS-456): resolve session timeout
• Include scope when relevant: feat(api): add authentication, fix(ui): resolve layout issue
• Use breaking change indicator: feat!: breaking API change or feat(api)!: breaking change to authentication
• Include quality check status in every PR (linting ✓, build ✓, test ✓)
• Use git-issue-updater for JIRA ticket updates with consistent format (user, date, time, PR details)
• Add JIRA comments immediately after PR creation for traceability
• Never skip the build or test steps - they catch production-breaking issues
• Commit linting, build, and test fixes separately for clarity
• Use semantic branch names (e.g., feature/IBIS-456-add-component)
• Review your own changes before submitting PR

Troubleshooting Checklist

Before creating PR:

• npm run lint passes with no errors
• npm run build completes successfully
• npm run test passes with no failures (BLOCKING)
• All tests pass (unit, integration, e2e)
• No skipped tests (unless documented)
• Coverage badge updated in README.md
• All changes are committed and staged
• Target branch is identified (main, develop, staging, etc. - not necessarily dev)
• Branch is up to date with target branch
• PLAN.md is updated if implementation changed
• JIRA ticket or git issue reference is identified
• PR body includes all necessary documentation

Semantic Versioning Labels

Add version bump labels to indicate release impact:

Label	Color	Description	Version Bump	Examples
major	#d73a4a (red)	Breaking changes	X.0.0	API removal, breaking refactor
minor	#fbca04 (yellow)	New features	0.X.0	New API, new component
patch	#0e8a16 (green)	Bug fixes	0.0.X	Bug fix, typo correction

Label Mapping from Commit Type:

• feat! or feat(scope)! → major (breaking change)
• feat → minor (new feature)
• fix → patch (bug fix)
• refactor → patch (code improvement)
• docs → patch (documentation)

Usage in Next.js PRs:

# Add version label to PR
gh pr edit <PR_NUMBER> --add-label "minor"

# During PR creation with Next.js feature
gh pr create --title "feat: add user dashboard" --add-label "minor"

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.