npm package: @functionform/nextie
Description: Scan Next.js repos for issues and fix them. Static analysis, auto-fix with tests, and PR creation.
Latest version: 1.8.2

# @functionform/nextie

Scan Next.js repos for issues, auto-fix them, and create PRs. Static analysis works out of the box — no API keys required.

## Quick Start

```bash
npx @functionform/nextie fix .
```

Or install globally:

```bash
npm install -g @functionform/nextie
nextie fix .
```

## Setup GitHub Action

Run the init command to create a GitHub Actions workflow in your project:

```bash
npx @functionform/nextie init --workflow
```

This creates `.github/workflows/nextie.yml` with manual trigger. Push to GitHub, then go to **Actions > Nextie > Run workflow**.

**Important:** The action needs permission to create branches and PRs. In your repo, go to **Settings > Actions > General**, scroll to **Workflow permissions**, and select:

- **Read and write permissions**
- **Allow GitHub Actions to create and approve pull requests**

## Features

- **8 analyzers** — typos, security, performance, type safety, error handling, code quality, testing, Next.js best practices
- **Auto-fix with tests** — only commits fixes that pass your test suite
- **Review mode** — creates one PR per fix, merge to accept, close to skip
- **Caching analysis** — detect opportunities for Next.js 16 `'use cache'` directive
- **AI-enhanced** (optional) — add an Anthropic API key for deeper analysis
- **Zero config** — works out of the box

## Commands

### `nextie fix <path>`

Scan and fix issues in a Next.js project.

```bash
nextie fix .                          # Fix issues in current directory
nextie fix . --dry-run                # Preview changes without applying
nextie fix . -i                       # Interactive mode — review each fix
nextie fix . --commit                 # Apply, test, and commit each fix
nextie fix . --analyzers security,performance  # Run specific analyzers
nextie fix . --exclude "src/legacy/**"         # Exclude paths
nextie fix . --threshold 0.9          # Higher confidence threshold
```

| Option | Description |
|--------|-------------|
| `--analyzers <categories>` | Comma-separated analyzer categories to run |
| `--threshold <number>` | Minimum confidence threshold, 0-1 (default: 0.8) |
| `--dry-run` | Show changes without applying |
| `-i, --interactive` | Review and apply fixes one at a time |
| `--commit` | Apply each fix, run tests, and commit individually |
| `--batch [groupBy]` | Group fixes by `file`, `category`, or `file-category` |
| `--test-command <cmd>` | Override the auto-detected test command |
| `--exclude <patterns>` | Comma-separated glob patterns to exclude |
| `--review` | Output fixes as JSON for CI review mode |
| `--pr` | Create PRs for fixes |
| `--branch <branch>` | Base branch name (default: main) |
| `--report-file <path>` | Write markdown report to file |
| `--result-file <path>` | Write JSON results to file |
| `--provider <provider>` | AI provider: `anthropic` or `ollama` |
| `--model <model>` | AI model to use |

### `nextie analyze <path>`

Scan without fixing — just report issues.

```bash
nextie analyze .
nextie analyze . --format json
nextie analyze . --output report.md --format markdown
```

| Option | Description |
|--------|-------------|
| `--analyzers <categories>` | Comma-separated analyzer categories |
| `--threshold <number>` | Minimum confidence threshold |
| `--format <format>` | Output format: `console`, `markdown`, `json` |
| `--output <path>` | Write report to file |

### `nextie cache <path>`

Find caching opportunities for Next.js 16's `'use cache'` directive.

```bash
nextie cache .
nextie cache . --setup                # Interactively add caching
nextie cache . --profile days         # Suggest longer cache lifetimes
nextie cache . --dry-run              # Preview without modifying
```

| Option | Description |
|--------|-------------|
| `--setup` | Interactively add caching to components |
| `--profile <profile>` | Cache profile: `default`, `minutes`, `hours`, `days`, `weeks`, `max` |
| `--dry-run` | Preview changes without modifying files |

### `nextie init [path]`

Set up nextie in your project.

```bash
nextie init                           # Create .nextierc.json
nextie init --workflow                # Also create GitHub Actions workflow
nextie init --force                   # Overwrite existing files
```

| Option | Description |
|--------|-------------|
| `--workflow` | Also create `.github/workflows/nextie.yml` |
| `--force` | Overwrite existing files |

### Other Commands

```bash
nextie deps <path>                    # Check for outdated packages
nextie upgrade [path]                 # Upgrade Next.js with codemods
nextie report <repo-url>              # Generate a detailed report
```

## Analyzer Categories

| Category | What it checks |
|----------|---------------|
| `typos` | Misspelled words in code and strings |
| `security` | Common security vulnerabilities |
| `performance` | Performance anti-patterns, raw `<a>` and `<img>` tags |
| `type-safety` | TypeScript type issues |
| `error-handling` | Missing error boundaries, empty catch blocks |
| `code-quality` | Code smell and maintainability |
| `testing` | Test coverage gaps |
| `nextjs` | Next.js-specific best practices |

## Configuration

Create a `.nextierc.json` (or run `nextie init`):

```json
{
  "threshold": 0.8,
  "testRetries": 2,
  "exclude": ["src/legacy/**"],
  "analyzers": {
    "typos": { "enabled": true },
    "security": { "enabled": true },
    "performance": { "enabled": true }
  }
}
```

## GitHub Action

For CI/CD usage, see [nathanaelphilip/nextie-action](https://github.com/nathanaelphilip/nextie-action).

## License

MIT