# next-go-modules

**Repository Path**: normalcoder/next-go-modules

## Basic Information

- **Project Name**: next-go-modules
- **Description**: 为 Next.js 13+ 设计的 Go Modules 代理中间件，完美支持 Vercel。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://www.npmjs.com/package/next-go-modules
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-18
- **Last Updated**: 2025-08-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: nextjs, go-modules, next-middleware, go-proxy

## README

# next-go-modules

![NPM Version](https://img.shields.io/npm/v/next-go-modules)
[![LICENSE](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
![Top language](https://img.shields.io/github/languages/top/normal-coder/next-go-modules)

![social preview for next-go-modules](./images/next-go-modules.png)

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

[English](./README.md) | [中文](./README.zh-cn.md)

## Features

- ✅ Out-of-the-box, simple configuration
- ✅ Support for personalized Go Modules addresses with aliases
- ✅ No Nginx dependency, perfect Vercel deployment support
- ✅ Minimum compatibility with Next.js 13
- ✅ TypeScript support, configurable caching, debug mode

## Installation

```bash
# 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)

```bash
# 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

```typescript
// 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

```typescript
// 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 goModulesMiddleware

export const config = {
  matcher: [
    '/((?!api|_next/static|_next/image|favicon.ico|manifest.webmanifest|sitemap.xml).*)',
  ],
}
```

#### 3. Create your API route

```typescript
// 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:

```typescript
// 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:

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

## Configuration Options

### GoModule

```typescript
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

```typescript
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

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

## Advanced Usage

### Custom API Route

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

### Custom Cache Control

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

### Custom Matcher

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

### Debug Mode

```typescript
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:

```typescript
// 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

```typescript
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

```bash
# 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](https://conventionalcommits.org/):

```bash
# 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](https://github.com/changesets/changesets) for version management:

```bash
# 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](https://nextjs.org/) - React full-stack framework
- [TypeScript](https://www.typescriptlang.org/)
- [ESLint](https://eslint.org/)
- [Husky](https://typicode.github.io/husky/)
- [Changesets](https://github.com/changesets/changesets)
- [Commitizen](https://commitizen-tools.github.io/commitizen/)

## License

[MIT License](./LICENSE) - see LICENSE file for details.