Next Modular

A modular architecture system for Next.js applications that enables building reusable, self-contained modules with their own routes, API endpoints, and middleware.

Features

Route Modules: Define page routes within modules
API Endpoints: Create module-specific API routes with dynamic parameters
Middleware: Add module-level middleware logic
Type-Safe: Full TypeScript support
CLI Tools: Initialize, add, and create modules with interactive CLI
Easy Integration: Simple configuration in Next.js apps

Quick Start

Using the CLI (Recommended)

# Initialize a Next.js app for Next Modular
npx next-modular init

# Add modules from registry
npx next-modular add @next-modular/auth-module

# Create custom modules
npx next-modular create --name my-module

# Start your app
npm run dev

Manual Setup

# 1. Install dependencies
npm install next-modular

# 2. Initialize your Next.js app
npx next-modular init

# 3. Start developing
npm run dev

CLI Commands

`next-modular init`

Initialize a Next.js app to use Next Modular. Creates all necessary files:

Catch-all routes (app/[...module]/page.tsx)
Catch-all API routes (app/api/[...module]/route.ts)
Middleware/proxy file (proxy.ts)
Configuration files (modules.config.ts, next-modular.runtime.ts)

npx next-modular init
npx next-modular init --directory ./my-app

`next-modular add [module]`

Add modules from the registry or npm:

# Interactive - shows list of available modules
npx next-modular add

# Add specific module
npx next-modular add @next-modular/auth-module

# Add custom npm package
npx next-modular add @your-org/custom-module

# Skip confirmation
npx next-modular add @next-modular/auth-module --yes

Available Modules:

@next-modular/auth-module - Authentication with login, register, password reset
@next-modular/test-module - Example module with routes, API, and middleware
Custom npm packages

`next-modular create`

Create a new local module with interactive setup:

# Interactive mode
npx next-modular create

# With options
npx next-modular create --name my-module --path modules

Features:

Interactive module name validation
Customizable path (default: modules/)
Choose features: Routes, API endpoints, Middleware, TypeScript
Auto-updates modules.config.ts
Generates complete module structure with examples

Project Structure

your-app/
├── app/
│   ├── [...module]/
│   │   └── page.tsx           # Catch-all route for module pages
│   ├── api/
│   │   └── [...module]/
│   │       └── route.ts       # Catch-all API route
│   └── page.tsx
├── modules/                   # Your local modules (created with 'create')
│   └── my-module/
│       └── src/
│           ├── routes/        # Module pages
│           ├── server/        # Server-side logic
│           │   ├── api/       # API handlers
│           │   └── middleware.ts
│           └── index.ts       # Module definition
├── modules.config.ts          # Centralized module configuration
├── next-modular.runtime.ts    # Runtime initialization
├── proxy.ts                   # Middleware
└── next.config.ts

How It Works

Module Definition

Modules are defined using defineModule:

import { defineModule } from 'next-modular';
import HomePage from './routes/home';
import { handleApi } from './server/api';
import { middleware } from './server/middleware';

export const myModule = defineModule({
  name: 'my-module',
  basePath: '/my-module',
  routes: [
    { path: '/home', component: HomePage },
    { path: '/about', component: AboutPage },
    { path: '/users/[id]', component: UserDetailPage }, // Dynamic routes
  ],
  apiRoutes: [
    { path: '/hello', handler: handleApi },
    { path: '/users/[id]', handler: getUserHandler }, // Dynamic API routes
  ],
  middleware: {
    handler: middleware,
  },
});

Module Configuration

Create a centralized modules.config.ts:

import { authModule } from '@next-modular/auth-module';
import { myModule } from './modules/my-module/src';

export const modules = [
  authModule,
  myModule,
];

Update next.config.ts:

import { withNextModular } from "next-modular/config";
import { modules } from "./modules.config";

const nextConfig = {
  /* your config */
};

export default withNextModular({
  modules,
})(nextConfig);

Update next-modular.runtime.ts:

import { configureModules } from 'next-modular';
import { modules } from './modules.config';

configureModules({ modules });
export { modules };

Module Configuration Options

Modules support custom configuration:

// Define config interface
export interface MyModuleConfig {
  apiKey?: string;
  timeout?: number;
  enableFeature?: boolean;
}

// Create module with config support
export const myModule = defineModule<MyModuleConfig>({
  name: 'my-module',
  basePath: '/my-module',
  config: {
    // Default configuration
    apiKey: '',
    timeout: 5000,
    enableFeature: true,
  },
  routes: [/* ... */],
  apiRoutes: [/* ... */],
});

Use with custom configuration:

// modules.config.ts
export const modules = [
  myModule({
    apiKey: process.env.MY_API_KEY,
    timeout: 10000,
    enableFeature: false,
  }),
];

Access config in handlers:

import { getModuleConfig } from 'next-modular';
import { MyModuleConfig } from '../index';

export async function handler(req: Request) {
  const config = getModuleConfig<MyModuleConfig>('my-module');
  
  if (config?.enableFeature) {
    // Do something
  }
  
  return new Response(JSON.stringify({ config }));
}

Request Flow

Page Request → Catch-all route [...module]/page.tsx → handleRoute() → Module component
API Request → Catch-all API route api/[...module]/route.ts → handleApiRoute() → Module handler
Middleware → proxy.ts → handleMiddleware() → Module middleware

Creating Modules

Using CLI (Recommended)

npx next-modular create --name blog

This creates a complete module structure with starter files.

Manual Creation

1. Create Module Structure

mkdir -p modules/blog/src/{routes,server/api}
cd modules/blog
npm init -y

2. Add Dependencies

{
  "name": "@your-org/blog",
  "peerDependencies": {
    "next": ">=14.0.0",
    "react": ">=18.0.0",
    "next-modular": "*"
  }
}

3. Create Components

modules/blog/src/routes/home.tsx:

export default function BlogHome() {
  return (
    <div>
      <h1>Blog</h1>
      <p>Welcome to the blog!</p>
    </div>
  );
}

4. Create API Handlers

modules/blog/src/server/api/posts.ts:

export async function handlePosts(req: Request) {
  const posts = [
    { id: 1, title: 'First Post' },
    { id: 2, title: 'Second Post' },
  ];
  
  return new Response(JSON.stringify(posts), {
    headers: { 'Content-Type': 'application/json' },
  });
}

5. Define Module

modules/blog/src/index.ts:

import { defineModule } from 'next-modular';
import BlogHome from './routes/home';
import { handlePosts } from './server/api/posts';

export const blogModule = defineModule({
  name: 'blog',
  basePath: '/blog',
  routes: [
    { path: '/home', component: BlogHome },
  ],
  apiRoutes: [
    { path: '/posts', handler: handlePosts },
  ],
});

6. Register Module

Add to modules.config.ts:

import { blogModule } from './modules/blog/src';

export const modules = [
  authModule,
  blogModule, // Add your new module
];

Dynamic Routes

Modules support dynamic route parameters:

// Route with dynamic segment
{ path: '/products/[id]', component: ProductDetail }

// API with dynamic segment
{ path: '/api/products/[id]', handler: getProduct }

// Access parameters in component
export default function ProductDetail({ params }: { params?: Record<string, string> }) {
  const productId = params?.id;
  return <div>Product: {productId}</div>;
}

// Access parameters in API handler
export async function getProduct(req: Request, context: any) {
  const productId = context.params?.id;
  return new Response(JSON.stringify({ id: productId }));
}

Example Modules

Auth Module

The included @next-modular/auth-module demonstrates:

Routes: Login (/auth/login), register (/auth/register), forgot password (/auth/forgot-password)
API Endpoints:
- POST /api/auth/login - User login
- POST /api/auth/register - User registration
- POST /api/auth/logout - User logout
- GET /api/auth/session - Get current session
Middleware: Request logging and authentication checking
Mock Implementation: Ready-to-customize authentication logic

Test Module

The @next-modular/test-module showcases:

Static Routes: /test, /test/about
Dynamic Routes: /test/products/[id], /test/users/[username]
API Endpoints: Hello, status, products CRUD, users
Middleware: Request logging and custom headers

Testing Your Module

# Start the development server
cd apps/test-app
npm run dev

Visit your module routes:

http://localhost:3010/your-module/home
http://localhost:3010/api/your-module/endpoint

Test API endpoints:

curl http://localhost:3010/api/your-module/hello

Development

Watch Mode

For development with hot reload:

# Terminal 1 - Watch module changes
cd modules/my-module && npm run dev

# Terminal 2 - Run Next.js app
cd apps/your-app && npm run dev

Building

# Build specific module
cd modules/my-module && npm run build

# Build all packages (in monorepo)
npm run build

Architecture Benefits

Modularity: Self-contained modules with their own routes, API, and logic
Reusability: Share modules across multiple Next.js applications
Type Safety: Full TypeScript support throughout
Scalability: Easy to add, remove, or update modules
Separation of Concerns: Each module manages its own functionality
Maintainability: Clear structure and boundaries between modules
Configuration: Per-module configuration with type safety
Dynamic Routing: Support for dynamic route parameters

Advanced Features

Environment-Based Configuration

const isDevelopment = process.env.NODE_ENV === 'development';

export const modules = [
  myModule({
    enableLogging: isDevelopment,
    apiRateLimit: isDevelopment ? 1000 : 100,
  }),
];

Feature Flags

export const modules = [
  myModule({
    features: {
      newFeature: process.env.ENABLE_NEW_FEATURE === 'true',
    },
  }),
];

Module-Level Middleware

import { NextRequest } from 'next/server';

export async function middleware(req: NextRequest) {
  console.log(`[My Module] ${req.method} ${req.url}`);
  
  // Add custom headers
  const response = NextResponse.next();
  response.headers.set('X-Module', 'my-module');
  return response;
}

API Reference

`defineModule<TConfig>(definition: ModuleDefinition)`

Defines a new module with routes, API endpoints, and middleware.

Parameters:

name - Unique module identifier
basePath - Base URL path for the module
config - Default configuration (optional)
routes - Array of page routes
apiRoutes - Array of API endpoints
middleware - Middleware handler (optional)

`handleRoute(pathname: string)`

Matches a pathname to a module route and returns the component.

`handleApiRoute(req: Request, pathname: string, context?: any)`

Handles API route requests and returns a Response.

`handleMiddleware(req: NextRequest)`

Executes middleware for matching modules.

`withNextModular(config: NextModularConfig)`

Next.js config plugin that registers modules.

`getModuleConfig<T>(moduleName: string)`

Retrieves module configuration at runtime.

Package Documentation

next-modular - Core package documentation
auth-module - Authentication module
test-module - Test/example module

Troubleshooting

Module not found

Make sure you:

Built the module (npm run build in the module directory)
Installed dependencies (npm install)
Registered the module in modules.config.ts
Imported the module configuration in next.config.ts and next-modular.runtime.ts

Route not working

Check that:

The module is registered
The basePath and path are correct
The component is exported as default
You've restarted the dev server

API endpoint not working

Verify:

The API route handler is properly defined
The path pattern matches your request
The HTTP method is supported in the catch-all route
Check server console for errors

TypeScript errors

Run:

npm run build

Check for linting errors and fix them.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
.github/workflows		.github/workflows
cli		cli
demo/demo-app		demo/demo-app
src		src
.gitignore		.gitignore
.npmignore		.npmignore
.releaserc.json		.releaserc.json
LICENSE		LICENSE
README.md		README.md
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

Next Modular

Features

Quick Start

Using the CLI (Recommended)

Manual Setup

CLI Commands

next-modular init

next-modular add [module]

next-modular create

Project Structure

How It Works

Module Definition

Module Configuration

Module Configuration Options

Request Flow

Creating Modules

Using CLI (Recommended)

Manual Creation

1. Create Module Structure

2. Add Dependencies

3. Create Components

4. Create API Handlers

5. Define Module

6. Register Module

Dynamic Routes

Example Modules

Auth Module

Test Module

Testing Your Module

Development

Watch Mode

Building

Architecture Benefits

Advanced Features

Environment-Based Configuration

Feature Flags

Module-Level Middleware

API Reference

defineModule<TConfig>(definition: ModuleDefinition)

handleRoute(pathname: string)

handleApiRoute(req: Request, pathname: string, context?: any)

handleMiddleware(req: NextRequest)

withNextModular(config: NextModularConfig)

getModuleConfig<T>(moduleName: string)

Package Documentation

Troubleshooting

Module not found

Route not working

API endpoint not working

TypeScript errors

Contributing

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 4

Contributors

Uh oh!

Languages

`next-modular init`

`next-modular add [module]`

`next-modular create`

`defineModule<TConfig>(definition: ModuleDefinition)`

`handleRoute(pathname: string)`

`handleApiRoute(req: Request, pathname: string, context?: any)`

`handleMiddleware(req: NextRequest)`

`withNextModular(config: NextModularConfig)`

`getModuleConfig<T>(moduleName: string)`