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.ts
import { GoModulesConfig } from 'next-go-modules'

export const goModulesConfig: 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'

const goModulesMiddleware = createGoModulesMiddleware({
  config: goModulesConfig,
  debug: process.env.NODE_ENV === 'development',
})

export default function middleware(request: any) {
  return goModulesMiddleware(request)
}

export const config = {
  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'

export const GET = createGoModulesApiRoute(goModulesConfig)
export const HEAD = 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'

export default createGoModulesApiRoute(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

interface GoModule {
  name: string // Module name
  fullName: string // Full module path (e.g., 'example.com/module')
  repo: string // Repository URL
  description: string // Module description
  install: string // Installation command
  tags?: string[] // Optional tags
  version?: string // Optional version
  aliases?: string[] // Optional aliases
}

GoModulesConfig

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

MiddlewareOptions

interface MiddlewareOptions {
  config: GoModulesConfig
  debug?: boolean // Enable debug logging
}

Advanced Usage

Custom API Route

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

Custom Cache Control

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

Custom Matcher

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

Debug Mode

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

Integration with Existing Middleware

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

// middleware.ts
import { composeMiddleware, createGoModulesMiddleware } from 'next-go-modules'
import { goModulesConfig } from './config/go-modules'

// Your existing middleware
function yourExistingMiddleware(request) {
  // Your logic
}

// Go modules middleware
const goModulesMiddleware = createGoModulesMiddleware({
  config: goModulesConfig,
  debug: process.env.NODE_ENV === 'development',
})

// Compose middlewares
export default composeMiddleware(
  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

const config: 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.