https://github.com/normal-coder/next-go-modules
Go Modules proxy middleware designed for Next.js 13+, with perfect Vercel support.
https://github.com/normal-coder/next-go-modules
go-modules go-proxy next-middleware nextjs nextjs-middleware
Last synced: about 7 hours ago
JSON representation
Go Modules proxy middleware designed for Next.js 13+, with perfect Vercel support.
- Host: GitHub
- URL: https://github.com/normal-coder/next-go-modules
- Owner: normal-coder
- License: mit
- Created: 2025-08-17T16:35:57.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-08-18T22:01:53.000Z (10 months ago)
- Last Synced: 2025-09-11T01:15:51.913Z (10 months ago)
- Topics: go-modules, go-proxy, next-middleware, nextjs, nextjs-middleware
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/next-go-modules
- Size: 127 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# next-go-modules
[](./LICENSE)
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
- ✅ 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
```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
**Option A: Using the helper function (Recommended for Next.js 15)**
```typescript
// 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
```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
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.