# Nextjs Pr Workflow

> 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.

- Skill: `tomevault-io/nextjs-pr-workflow` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/nextjs-pr-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/nextjs-pr-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/nextjs-pr-workflow

---


## 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:
```bash
# 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**:
```bash
# 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:**
```bash
# 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:
```bash
# 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:
```bash
# 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:
```markdown
# 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**:
```bash
# 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](https://tomevault.io/claim/darellchua2) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->