Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Plugin Activation
✓ plugins:
- serverless-go-plugin
✗ import 'serverless-go-plugin'; // Incorrect for Serverless plugins
// OR
const plugin = require('serverless-go-plugin');
This plugin is activated by listing its name under the `plugins` section in your `serverless.yaml` file, not via standard JavaScript/TypeScript `import` or `require` statements.
Go Function Handler Definition
✓ functions:
myGoFunc:
runtime: go1.x
handler: functions/myGoFunc/main.go
✗ functions:
myGoFunc:
runtime: go1.x
handler: myGoFunc // Assumes default JS/Node.js handler naming conventions
Specify the full path to the Go source file (`.go`) or the package directory containing `main.go` for the `handler` property. The plugin uses this path for compilation.
Custom Plugin Configuration
✓ custom:
go:
binDir: .bin
cgo: 1
monorepo: true
✗ custom:
go: { binDir: ".bin" } // Valid YAML but less readable; also, direct programmatic access via JS is not applicable
Plugin-specific settings like `binDir`, `cgo`, or `monorepo` are defined under the `custom.go` section in `serverless.yaml`.
This quickstart demonstrates how to set up a Serverless project with `serverless-go-plugin` to deploy Go functions. It includes a `package.json` for dependencies, a `serverless.yaml` configured for both standard `go1.x` and `provided.al2` (ARM64) runtimes, and two example Go Lambda functions (`hello` and `greet`). The `greet` function illustrates using path parameters and environment variables.
{
"name": "my-go-serverless-app",
"version": "1.0.0",
"description": "A serverless Go application with serverless-go-plugin",
"main": "handler.js",
"scripts": {
"deploy": "serverless deploy"
},
"keywords": [],
"author": "",
"license": "ISC",
"devDependencies": {
"serverless": "^3.0.0",
"serverless-go-plugin": "^2.0.0",
"@aws-cdk/aws-lambda": "^1.0.0"
}
}
// serverless.yaml
service: my-go-app
frameworkVersion: '3'
provider:
name: aws
runtime: go1.x # Default runtime, can be overridden per function
region: us-east-1
architecture: x86_64 # Default architecture
plugins:
- serverless-go-plugin
custom:
go:
binDir: .bin # Target folder for compiled binaries
cmd: 'GOOS=linux go build -ldflags="-s -w"' # Default compile command
supportedRuntimes: ["go1.x", "provided.al2"]
functions:
hello:
handler: functions/hello/main.go # Path to the Go source file
events:
- httpApi:
path: /hello
method: get
greetArm:
runtime: provided.al2 # Example for a bootstrapped runtime
handler: functions/greet # Package path (assuming main.go inside)
architecture: arm64
environment:
MESSAGE: "Hello from ARM64 Go Lambda!"
events:
- httpApi:
path: /greet/{name}
method: get
// functions/hello/main.go
package main
import (
"context"
"fmt"
"github.com/aws/aws-lambda-go/events"
"github.com/aws/aws-lambda-go/lambda"
)
type Response events.APIGatewayProxyResponse
func Handler(ctx context.Context, request events.APIGatewayProxyRequest) (Response, error) {
body := fmt.Sprintf("Hello from Go Lambda on x86_64! Path: %s", request.Path)
resp := Response{
StatusCode: 200,
IsBase64Encoded: false,
Body: body,
Headers: map[string]string{
"Content-Type": "application/json"
},
}
return resp, nil
}
func main() {
lambda.Start(Handler)
}
// functions/greet/main.go
package main
import (
"context"
"fmt"
"net/http"
"os"
"github.com/aws/aws-lambda-go/events"
"github.com/aws/aws-lambda-go/lambda"
)
func GreetHandler(ctx context.Context, request events.APIGatewayProxyRequest) (events.APIGatewayProxyResponse, error) {
name := request.PathParameters["name"]
if name == "" {
name = "stranger"
}
messageEnv := os.Getenv("MESSAGE")
message := fmt.Sprintf("%s Greetings, %s!", messageEnv, name)
return events.APIGatewayProxyResponse{
StatusCode: http.StatusOK,
Headers: map[string]string{"Content-Type": "text/plain"},
Body: message,
},
nil
}
func main() {
lambda.Start(GreetHandler)
}
Errors
Common errors & fixes
Error: Cannot find module 'serverless-go-plugin'
Attempting to `require` or `import` the plugin in a JavaScript/TypeScript file, instead of configuring it in `serverless.yaml`.
fixRemove any JavaScript/TypeScript `require` or `import` statements for `serverless-go-plugin`. Ensure the plugin is listed correctly under the `plugins` section in your `serverless.yaml` file: `plugins: - serverless-go-plugin`.
go build <module path> failed with exit status 1
A generic Go compilation error indicating an issue with your Go source code, build environment, or `cmd` configuration.
fixReview your Go source code for syntax errors, missing dependencies (check `go.mod`), or type mismatches. Verify your `custom.go.cmd` setting for any incorrect build flags or commands. Ensure Go is correctly installed and accessible in your environment.
Lambda Validation Error: Your handler 'bootstrap' is not found in the deployment package.
This error often occurs when deploying to `provided.al2` or similar custom runtimes without correctly configuring the plugin to build a `bootstrap` executable or without including it in the package.
fixEnsure `runtime: provided.al2` is set for the function and that `custom.go.buildProvidedRuntimeAsBootstrap: true` is enabled in your plugin configuration. Also, append `GOARCH=arm64` (or target architecture) to your `custom.go.cmd`.
Audit
Dependencies
serverlessrequiredRequired to run the plugin within the Serverless Framework ecosystem. The plugin requires Serverless Framework version 1.52 and above.