{"id":15232,"library":"serverless-go-plugin","title":"Serverless Go Plugin","description":"This Serverless Framework plugin, currently at version 2.4.1, automates the compilation of Go functions for AWS Lambda deployments. It integrates directly with Serverless Framework commands like `deploy`, `deploy function`, and `invoke local`, compiling Go source code on the fly before packaging. Key differentiators include concurrent compilation across all CPU cores for efficiency, support for various Go runtimes including `go1.x` and `provided.al2` (with bootstrap), and features for monorepo-like project structures. The plugin manages handler path transformations and package exclusions/inclusions, simplifying the deployment workflow for Go-based serverless applications. Releases generally include minor feature enhancements, dependency updates, and bug fixes, maintaining an active development cadence. It specifically requires Serverless Framework version 1.52 or above to function.","status":"active","version":"2.4.1","language":"javascript","source_language":"en","source_url":"https://github.com/mthenw/serverless-go-plugin","tags":["javascript","serverless","serverless framework","serverless plugin","amazon web services","awslambda","golang","go"],"install":[{"cmd":"npm install serverless-go-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add serverless-go-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add serverless-go-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required to run the plugin within the Serverless Framework ecosystem. The plugin requires Serverless Framework version 1.52 and above.","package":"serverless","optional":false}],"imports":[{"note":"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.","wrong":"import 'serverless-go-plugin'; // Incorrect for Serverless plugins\n// OR\nconst plugin = require('serverless-go-plugin');","symbol":"Plugin Activation","correct":"plugins:\n  - serverless-go-plugin"},{"note":"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.","wrong":"functions:\n  myGoFunc:\n    runtime: go1.x\n    handler: myGoFunc // Assumes default JS/Node.js handler naming conventions","symbol":"Go Function Handler Definition","correct":"functions:\n  myGoFunc:\n    runtime: go1.x\n    handler: functions/myGoFunc/main.go"},{"note":"Plugin-specific settings like `binDir`, `cgo`, or `monorepo` are defined under the `custom.go` section in `serverless.yaml`.","wrong":"custom:\n  go: { binDir: \".bin\" } // Valid YAML but less readable; also, direct programmatic access via JS is not applicable","symbol":"Custom Plugin Configuration","correct":"custom:\n  go:\n    binDir: .bin\n    cgo: 1\n    monorepo: true"}],"quickstart":{"code":"{\n  \"name\": \"my-go-serverless-app\",\n  \"version\": \"1.0.0\",\n  \"description\": \"A serverless Go application with serverless-go-plugin\",\n  \"main\": \"handler.js\",\n  \"scripts\": {\n    \"deploy\": \"serverless deploy\"\n  },\n  \"keywords\": [],\n  \"author\": \"\",\n  \"license\": \"ISC\",\n  \"devDependencies\": {\n    \"serverless\": \"^3.0.0\",\n    \"serverless-go-plugin\": \"^2.0.0\",\n    \"@aws-cdk/aws-lambda\": \"^1.0.0\"\n  }\n}\n\n// serverless.yaml\nservice: my-go-app\n\nframeworkVersion: '3'\n\nprovider:\n  name: aws\n  runtime: go1.x # Default runtime, can be overridden per function\n  region: us-east-1\n  architecture: x86_64 # Default architecture\n\nplugins:\n  - serverless-go-plugin\n\ncustom:\n  go:\n    binDir: .bin # Target folder for compiled binaries\n    cmd: 'GOOS=linux go build -ldflags=\"-s -w\"' # Default compile command\n    supportedRuntimes: [\"go1.x\", \"provided.al2\"]\n\nfunctions:\n  hello:\n    handler: functions/hello/main.go # Path to the Go source file\n    events:\n      - httpApi:\n          path: /hello\n          method: get\n  greetArm:\n    runtime: provided.al2 # Example for a bootstrapped runtime\n    handler: functions/greet # Package path (assuming main.go inside)\n    architecture: arm64\n    environment:\n      MESSAGE: \"Hello from ARM64 Go Lambda!\"\n    events:\n      - httpApi:\n          path: /greet/{name}\n          method: get\n\n\n// functions/hello/main.go\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"github.com/aws/aws-lambda-go/events\"\n\t\"github.com/aws/aws-lambda-go/lambda\"\n)\n\ntype Response events.APIGatewayProxyResponse\n\nfunc Handler(ctx context.Context, request events.APIGatewayProxyRequest) (Response, error) {\n\tbody := fmt.Sprintf(\"Hello from Go Lambda on x86_64! Path: %s\", request.Path)\n\tresp := Response{\n\t\tStatusCode:      200,\n\t\tIsBase64Encoded: false,\n\t\tBody:            body,\n\t\tHeaders: map[string]string{\n\t\t\t\"Content-Type\": \"application/json\"\n\t\t},\n\t}\n\treturn resp, nil\n}\n\nfunc main() {\n\tlambda.Start(Handler)\n}\n\n// functions/greet/main.go\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"net/http\"\n\t\"os\"\n\n\t\"github.com/aws/aws-lambda-go/events\"\n\t\"github.com/aws/aws-lambda-go/lambda\"\n)\n\nfunc GreetHandler(ctx context.Context, request events.APIGatewayProxyRequest) (events.APIGatewayProxyResponse, error) {\n\tname := request.PathParameters[\"name\"]\n\tif name == \"\" {\n\t\tname = \"stranger\"\n\t}\n\tmessageEnv := os.Getenv(\"MESSAGE\")\n\tmessage := fmt.Sprintf(\"%s Greetings, %s!\", messageEnv, name)\n\n\treturn events.APIGatewayProxyResponse{\n\t\tStatusCode: http.StatusOK,\n\t\tHeaders:    map[string]string{\"Content-Type\": \"text/plain\"},\n\t\tBody:       message,\n\t},\n\tnil\n}\n\nfunc main() {\n\tlambda.Start(GreetHandler)\n}\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Implement a deployment strategy such as Canary deployments in your Serverless configuration or use traffic shifting features in AWS Lambda.","message":"When deploying Go Lambda functions on ARM64 architecture using `provided.al2` runtime, the very first deployment may result in a small downtime (a few seconds) as the new runtime initializes. Consider using a deployment strategy like canary deployments for safer rollouts.","severity":"gotcha","affected_versions":">=2.3.0"},{"fix":"Ensure your `handler` property in `serverless.yaml` points directly to the Go source file or its containing package directory, following the pattern: `handler: <path_to_function_directory>/main.go` or `handler: <path_to_function_directory>`.","message":"The `handler` property for Go functions must specify the path to the Go source file (e.g., `functions/myFunc/main.go`) or the package path (e.g., `functions/myFunc`). Unlike Node.js or Python, simply using the function name is incorrect and will lead to handler not found errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Adjust your `handler` paths to be relative to the `custom.go.baseDir` you've set, or omit `baseDir` if your Go modules are at the root of your project.","message":"If you configure the `custom.go.baseDir` property in `serverless.yaml`, all `handler` paths for your Go functions must be specified relative to this `baseDir`, not relative to the `serverless.yaml` file itself. Misconfiguration can lead to compilation failures or handlers not being found.","severity":"gotcha","affected_versions":">=1.3.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Remove 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`.","cause":"Attempting to `require` or `import` the plugin in a JavaScript/TypeScript file, instead of configuring it in `serverless.yaml`.","error":"Error: Cannot find module 'serverless-go-plugin'"},{"fix":"Review 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.","cause":"A generic Go compilation error indicating an issue with your Go source code, build environment, or `cmd` configuration.","error":"go build <module path> failed with exit status 1"},{"fix":"Ensure `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`.","cause":"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.","error":"Lambda Validation Error: Your handler 'bootstrap' is not found in the deployment package."}],"ecosystem":"npm"}