next-go-modules

Go Modules proxy middleware designed for Next.js 13+, with perfect Vercel support.

English | 中文

Features

• ✅ Out-of-the-box, simple configuration
• ✅ Support for personalized Go Modules addresses with aliases
• ✅ No Nginx dependency, perfect Vercel deployment support
• ✅ Compatible with Next.js 13.0+ (App Router & Pages Router)
• ✅ TypeScript support, configurable caching, debug mode
• ✅ Cross-version compatibility (avoids Next.js type conflicts)

Installation

# npm
npm install next-go-modules
# yarn
yarn add next-go-modules
# pnpm
pnpm add next-go-modules

Quick Start

Option 1: Using CLI Tool (Recommended)

# Auto-generate all necessary files
npx next-go-modules init
# Or if installed globally
next-go-modules init

This will automatically create:

• config/go-modules.ts - Module configuration file
• middleware.ts - Next.js middleware
• API route files (automatically detects App Router or Pages Router)

Then simply edit config/go-modules.ts to add your Go modules configuration.

Note

If your project already has a middleware.ts file, the CLI tool will provide integration guidance instead of overwriting the existing file.

Option 2: Manual Setup

1. Create your modules configuration

// config/go-modules.tsimport{GoModulesConfig}from'next-go-modules'exportconstgoModulesConfig: GoModulesConfig={modules: {'my-go-tool': {name: 'my-go-tool',fullName: 'yourdomain.com/my-go-tool',repo: 'https://github.com/yourusername/my-go-tool',description: 'Your Go tool description',install: 'go get -u yourdomain.com/my-go-tool',version: 'v1.0.0',aliases: ['tool'],// Optional aliases},// Add more modules here...},}

2. Create your middleware

Option A: Using the helper function (Recommended for Next.js 15)

// src/middleware.ts (if using src directory) or middleware.ts (project root)import{createGoModulesMiddleware}from'next-go-modules'import{goModulesConfig}from'./config/go-modules'constgoModulesMiddleware=createGoModulesMiddleware({config: goModulesConfig,debug: process.env.NODE_ENV==='development',})exportdefaultfunctionmiddleware(request: any){returngoModulesMiddleware(request)}exportconstconfig={matcher: ['/((?!api|_next/static|_next/image|favicon.ico|manifest.webmanifest|sitemap.xml).*)',],}

3. Create your API route

// app/api/go-modules/[...module]/route.ts (App Router)import{createGoModulesApiRoute,createGoModulesHeadRoute}from'next-go-modules'import{goModulesConfig}from'../../../../config/go-modules'exportconstGET=createGoModulesApiRoute(goModulesConfig)exportconstHEAD=createGoModulesHeadRoute(goModulesConfig)

Or using Pages Router:

// pages/api/go-modules/[...module].ts (Pages Router)import{createGoModulesApiRoute}from'next-go-modules'import{goModulesConfig}from'../../../config/go-modules'exportdefaultcreateGoModulesApiRoute(goModulesConfig)

Usage

Now your Go modules will be accessible at:

• /my-go-tool - Main path
• /tool - Alias path
• /my-go-tool?go-get=1 - With go-get parameter

Users can install your Go modules with:

go get -u yourdomain.com/my-go-tool

Configuration Options

GoModule

interfaceGoModule{name: string// Module namefullName: string// Full module path (e.g., 'example.com/module')repo: string// Repository URLdescription: string// Module descriptioninstall: string// Installation commandtags?: string[]// Optional tagsversion?: string// Optional versionaliases?: string[]// Optional aliases}

GoModulesConfig

interfaceGoModulesConfig{modules: Record<string,GoModule>apiRoute?: string// Default: '/api/go-modules'matcher?: string[]// Default: excludes static filescacheControl?: string// Default: 'public, max-age=3600'}

MiddlewareOptions

interfaceMiddlewareOptions{config: GoModulesConfigdebug?: boolean// Enable debug logging}

Advanced Usage

Custom API Route

constconfig: GoModulesConfig={modules: {/* your modules */},apiRoute: '/api/custom-go-modules',}

Custom Cache Control

constconfig: GoModulesConfig={modules: {/* your modules */},cacheControl: 'public, max-age=7200',// 2 hours}

Custom Matcher

constconfig: GoModulesConfig={modules: {/* your modules */},matcher: ['/((?!api|_next|favicon.ico).*)',],}

Debug Mode

constmiddleware=createGoModulesMiddleware({config: goModulesConfig,debug: true,// Enable console logging})

Integration with Existing Middleware

If you already have middleware, you can use the compose function:

// middleware.tsimport{composeMiddleware,createGoModulesMiddleware}from'next-go-modules'import{goModulesConfig}from'./config/go-modules'// Your existing middlewarefunctionyourExistingMiddleware(request){// Your logic}// Go modules middlewareconstgoModulesMiddleware=createGoModulesMiddleware({config: goModulesConfig,debug: process.env.NODE_ENV==='development',})// Compose middlewaresexportdefaultcomposeMiddleware(goModulesMiddleware,yourExistingMiddleware)

API Reference

Core Functions

• getGoModule(modulePath, modules) - Get module by path or alias
• getAllGoModules(modules) - Get all modules
• getAllModulePaths(modules) - Get all available paths
• generateGoModuleHTML(module) - Generate HTML for module

Middleware Functions

• createGoModulesMiddleware(options) - Create middleware function
• getGoModulesMiddlewareConfig(options) - Get middleware config

API Route Functions

• createGoModulesApiRoute(config) - Create GET handler
• createGoModulesHeadRoute(config) - Create HEAD handler

Examples

Multiple Modules with Aliases

constconfig: GoModulesConfig={modules: {'go-masker': {name: 'go-masker',fullName: 'normalcoder.com/go-masker',repo: 'https://github.com/normal-coder/go-masker',description: 'Data masking tool',install: 'go get -u normalcoder.com/go-masker',aliases: ['masker','data-masker'],},'go-validator': {name: 'go-validator',fullName: 'normalcoder.com/go-validator',repo: 'https://github.com/normal-coder/go-validator',description: 'Data validation tool',install: 'go get -u normalcoder.com/go-validator',aliases: ['validator','validate'],},},}

This supports:

• /go-masker, /masker, /data-masker
• /go-validator, /validator, /validate

Deployment

Vercel

This package works seamlessly with Vercel deployment. No additional configuration needed.

Other Platforms

The middleware is compatible with any platform that supports Next.js middleware.

Development

Development Setup

# Clone repository
git clone https://github.com/normal-coder/next-go-modules.git
cd next-go-modules
# Install dependencies
pnpm install
# Development mode
pnpm dev
# Lint code
pnpm lint
# Build
pnpm build

Commit Convention

This project uses Conventional Commits:

# Use commitizen for interactive commits
pnpm commit
# Or manually follow the format
git commit -m "feat: add new feature"
git commit -m "fix: resolve issue"
git commit -m "docs: update readme"

Version Management

Using Changesets for version management:

# Add changeset
pnpm changeset
# Version packages
pnpm version
# Release to npm
pnpm release

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (pnpm commit)
4. Push to the branch (git push origin feature/amazing-feature)
5. Create a Pull Request

Acknowledgments

• Next.js - React full-stack framework
• TypeScript
• ESLint
• Husky
• Changesets
• Commitizen

License

MIT License - see LICENSE file for details.