next-affected
v1.0.0
Published
CLI tool to list Next.js pages affected by changes
Downloads
473
Readme
next-affected
next-affected
is a CLI tool that helps you identify which Next.js pages are affected by changes in your codebase. By analyzing your project's dependency graph, it determines which pages need to be rebuilt or retested, improving the efficiency of your development and CI/CD processes.
Table of Contents
Features
- Analyze Specific Components: Find out which Next.js pages are affected by changes in a specific component.
- Git Integration: Compare changes between Git commits or branches to identify affected pages.
- Include Uncommitted Changes: Optionally include uncommitted changes in your analysis.
- Only Uncommitted Changes: Analyze only uncommitted changes against a base commit or branch.
- Customizable: Supports custom configuration for page directories and file extensions to exclude.
- TypeScript Support: Works seamlessly with TypeScript and recognizes path aliases from
tsconfig.json
. - Verbose Logging: Provides detailed logs for better debugging and analysis.
Installation
You can install next-affected
globally or as a dev dependency in your project.
Install Globally
npm install -g next-affected
Install as a Dev Dependency
npm install --save-dev next-affected
Usage
After installation, you can use next-affected
directly from the command line.
Initialize Configuration
First, initialize the configuration file in your project:
next-affected init
This command creates a next-affected.config.json
file with default settings in your project's root directory.
Commands
init
Initialize next-affected
configuration.
next-affected init
run [componentPath]
List Next.js pages affected by changes.
next-affected run [componentPath] [options]
Options
-p, --project <path>
: Path to the Next.js project. Defaults to.
(current directory).-b, --base <commit>
: Base commit or branch to compare changes. Required when using--only-uncommitted
.-h, --head <commit>
: Head commit or branch to compare changes. Defaults toHEAD
.-u, --uncommitted
: Include uncommitted changes in the analysis.-o, --only-uncommitted
: Analyze only uncommitted changes against the base. Requires--base
.-d, --depth <number>
: Max depth for dependency traversal.-v, --verbose
: Enable verbose logging.
Examples
Analyze a Specific Component
Find all Next.js pages that are affected by changes in a specific component:
next-affected run src/components/Button.tsx
Include Uncommitted Changes
Analyze all changes including uncommitted (local) changes, listing the affected pages:
next-affected run --uncommitted --base main
Analyze Only Uncommitted Changes
Analyze only the uncommitted changes in your working directory against the main
branch:
next-affected run --only-uncommitted --base main
Note: The
--only-uncommitted
flag requires the--base
(-b
) flag to specify the base commit or branch.
Compare Changes Between Current Branch and main
Analyze all changes between your current branch and main
, listing the affected pages:
next-affected run --base main
Compare Changes Between Two Commits
Replace commit1
and commit2
with actual commit hashes or branch names:
next-affected run --base commit1 --head commit2
Specify Project Directory and Verbose Logging
next-affected run --project /path/to/your/project --verbose
Additional Help
For more detailed help and options, you can run:
next-affected run --help
Configuration
next-affected
uses a configuration file next-affected.config.json
to customize its behavior.
Default Configuration
{
"pagesDirectories": ["pages", "src/pages", "app", "src/app"],
"excludedExtensions": [".css", ".scss", ".less", ".svg", ".png", ".jpg"]
}
Configuration Options
pagesDirectories
: An array of directories where your Next.js pages are located. Customize this if your pages are in different directories.excludedExtensions
: An array of file extensions to exclude from the dependency analysis. Add any extensions that you don't want to consider in the analysis.
Customizing Configuration
You can edit the next-affected.config.json
file to suit your project's structure:
{
"pagesDirectories": ["src/customPages"],
"excludedExtensions": [".css", ".scss", ".less", ".svg", ".png", ".jpg", ".json"]
}
How It Works
next-affected
builds a dependency graph of your project and traverses it to find all pages that depend on a given component or have been affected by changes between Git commits or branches.
Steps:
- Build Dependency Graph: Uses madge to build the dependency graph of your project.
- Determine Changed Files: If using Git comparison mode (
--base
), it determines the list of changed files between the two commits or branches. If--uncommitted
or--only-uncommitted
is specified, it also includes uncommitted changes and untracked files. - Traverse Dependencies: For each changed file or specified component, it traverses the dependency graph to find all dependent modules, up to the specified depth.
- Identify Affected Pages: Filters the dependent modules to identify which are Next.js pages based on the configured
pagesDirectories
.
Troubleshooting
- No Affected Pages Found: Ensure that the paths in
pagesDirectories
are correct and point to your Next.js pages. - Errors Executing Git Command: Verify that the commits or branches specified in
--base
and--head
exist and are accessible. - Including Uncommitted Changes Not Working: Make sure you have saved your changes and that they are within the project directory specified.
--only-uncommitted
Flag Not Working: Ensure you are also specifying the--base
flag when using--only-uncommitted
.- Verbose Logging: Use the
--verbose
flag to enable detailed logging, which can help identify issues.
License
This project is licensed under the MIT License.
Contribute
Feel free to open issues or contribute to the project!