Next.js App Toolkit CLI

A powerful CLI tool to accelerate Next.js development by scaffolding features, components, and more with a single command.

Next.js App Toolkit is a command-line interface (CLI) designed to supercharge your Next.js development workflow. Eliminate repetitive boilerplate setup and generate feature-rich modules instantly, allowing you to focus on building core application logic.

Table of Contents

• Features
  • Next.js Proxy Rule Helper · guide
  • Complete Feature Module Generator
  • User Role RBPC
• Highlights
• Prerequisites
• Installation
  • Install as a project dev dependency
  • Install globally
  • Local build (development)
• Usage
  • Generate a Feature Module
  • Initialize the Next.js Proxy Toolkit · guide
• Commands API
• Documentation
• For Developers (Contributing)
• Author
• License

Features

1. Next.js Proxy Rule Helper

Docs: Using the Proxy Toolkit — full setup, config reference, and examples.

Bootstraps a Next.js proxy.ts entrypoint plus a reusable NextProxyToolkit that lets you declare route rules instead of hand-writing redirect logic. Each rule can define:

• matcher / exclude — which paths the rule applies to (and which to skip)
• condition — a callback over the NextAuth JWT that returns pass, fail, or a redirect URL
• failedUrl / successUrl — where to send the user, with optional callback URL or session-token append

Ideal for auth gates, role redirects, and other request-time routing without duplicating proxy code.

2. Complete Feature Module Generator

Scaffolds a full feature module under src/features/<name>/ so you can start building domain logic without writing boilerplate. Each module includes:

Piece	Purpose
config	Feature-level constants such as Next.js cache tags used with revalidateTag for on-demand revalidation.
hook	React Query hooks (e.g. usePaymentList) that fetch and cache feature data on the client.
service	Server Actions and fetch helpers for CRUD (get, getById, create, edit, delete) with cache revalidation.
slice	A Redux Toolkit slice for local feature state (items, status, error) and related reducers.
types	TypeScript interfaces that define the feature’s data model.
utils	Feature-scoped helper functions you can extend as the module grows.

3. User Role RBPC (Role-Based Permission Control)

Generates a typed permission system for controlling route access by user role. It includes:

• Roles — an enum of roles (e.g. ADMIN, GUEST)
• Permission config — per-role allow lists: canAll, canView, canInsert, canEdit, and canDelete
• Helpers — utilities to build route arrays from route maps and to check whether a role may access a given pathname (with optional path prefixes and exclusions)

Use this to keep authorization rules centralized and consistent across proxy/middleware checks and UI logic.

---

Highlights

• Rapid Scaffolding: Generate entire feature modules with a single command.
• Best Practices Included: Follows modern Next.js App Router patterns — Server Actions, revalidateTag, and React Query hooks.
• Type-Safe by Default: All generated files are TypeScript-based.
• Developer-Friendly: Simple command structure with short aliases.
• Package-manager agnostic: Works with npm, pnpm, yarn, and bun.
• Extensible Architecture: Easy to expand with new generators.

---

Prerequisites

Before installing or using the toolkit, make sure you have:

• Node.js 18 or later
• A package manager: npm, pnpm, yarn, or bun
• A Next.js App Router project (TypeScript recommended)

Generated code may also expect these packages in the target project:

Package	Used by
next-auth	Proxy Rule Helper (JWT / auth conditions)
@tanstack/react-query	Feature hooks
@reduxjs/toolkit	Feature slices

Install them in your Next.js app as needed before relying on the generated modules.

---

Installation

This project works with npm, pnpm, yarn, and bun.

Install as a project dev dependency

Add the package as a dev dependency in your Next.js project:

# npm
npm i -D nextjs-app-toolkit

# pnpm
pnpm add -D nextjs-app-toolkit

# yarn
yarn add -D nextjs-app-toolkit

# bun
bun add -d nextjs-app-toolkit

Then run the CLI via your package manager:

# npm
npx next-toolkit <command>

# pnpm
pnpm exec next-toolkit <command>

# yarn
yarn next-toolkit <command>

# bun
bunx next-toolkit <command>

Or add a script to your app’s package.json:

{
  "scripts": {
    "toolkit": "next-toolkit"
  }
}

npm run toolkit -- init:proxy

Install globally

Install once and use next-toolkit from any project:

# npm
npm i -g nextjs-app-toolkit

# pnpm
pnpm add -g nextjs-app-toolkit

# yarn
yarn global add nextjs-app-toolkit

# bun
bun add -g nextjs-app-toolkit

Then run:

next-toolkit <command> [options]

Local build (development)

Use this when contributing to the toolkit or testing unpublished changes.

1. Clone the Repository:

   git clone https://github.com/isweerasingha/nextjs-app-toolkit.git
   cd nextjs-app-toolkit

2. Install Dependencies:

   # npm
   npm install
   
   # pnpm
   pnpm install
   
   # yarn
   yarn
   
   # bun
   bun install

3. Build the Project: Compiles TypeScript into dist/ and copies template files:

   # npm
   npm run build
   
   # pnpm
   pnpm build
   
   # yarn
   yarn build
   
   # bun
   bun run build

4. Link for Local Testing: Makes the local CLI available globally as next-toolkit:

   # npm
   npm link
   
   # pnpm
   pnpm link --global
   
   # yarn
   yarn link
   
   # bun
   bun link

   After linking, rebuild whenever you change the source so the linked command picks up updates.

Usage

Navigate to the root directory of any Next.js project and run the toolkit’s commands.

If you installed as a dev dependency:

npx next-toolkit <command> [options]

If you installed globally or linked a local build:

next-toolkit <command> [options]

Generate a Feature Module

next-toolkit gen:feature payment
# or
next-toolkit gf payment

Creates a fully structured module at src/features/payment/:

src/features/payment/
├── config/
│   └── payment.config.ts
├── hooks/
│   └── payment.hooks.ts
├── services/
│   └── payment.service.ts
├── state/
│   └── payment.slice.ts
├── types/
│   └── payment.types.ts
├── utils/
│   └── payment.utils.ts
└── index.ts

Use a singular name for the feature argument (e.g. product, user, payment).

Initialize the Next.js Proxy Toolkit

Docs: Using the Proxy Toolkit — complete usage guide with examples.

next-toolkit init:proxy
# or
next-toolkit im

Scaffolds a Next.js Proxy entrypoint and the reusable toolkit under your project. By default, files are written relative to src/.

src/
├── proxy.ts
└── utils/
    └── NextProxyToolkit/
        ├── index.ts
        ├── toolkit.ts
        ├── types.ts
        └── utils.ts

Options

Option	Default	Description
-p, --path <string>	src	Base directory for generated files. Use / to place files at the project root.

Examples

# Default: generate under src/
next-toolkit init:proxy

# Generate under lib/
next-toolkit init:proxy --path lib

# Generate at the project root
next-toolkit init:proxy --path /

After running the command, update the proxy rules in the generated proxy.ts file. See the Proxy Toolkit guide for config details and examples.

---

Commands API

Command	Alias	Description
gen:feature <name>	gf	Generates a new feature module in src/features/. The <name> should be singular (e.g. product, user).
init:proxy	im	Initializes a Next.js Proxy setup with proxy.ts and the NextProxyToolkit utility. Supports -p, --path.

---

Documentation

Guide	Description
Proxy Toolkit	Full usage guide for init:proxy — setup, rule config, and examples

---

For Developers (Contributing)

Contributions are welcome! If you'd like to help improve the toolkit, please follow these steps to set up a local development environment.

---

Author

This project is maintained by Isuru Weerasingha.

• GitHub: @isweerasingha
• LinkedIn: linkedin.com/in/isweerasingha

License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for the full license text.