serverless-go-build

0.0.6 verified Sat Apr 25 auth: no javascript

A Serverless v1.x plugin to build Go binaries for AWS Lambda functions. Version 0.0.6 is the latest release as of the provided data. The plugin integrates with the Serverless Framework (v1.x) to automate building of Go code, allowing developers to specify .go files or module.Function as handlers in serverless.yml. Key differentiators: automatically builds all Go functions listed as handlers, supports individual packaging for reduced Lambda code size, runs Go tests with optional serverless plugin hooks, and is highly customizable via serverless.yml. It is less actively maintained compared to alternatives like serverless-go-plugin.

Common errors

error Error: ENOENT: no such file or directory, open 'generatedEntrypoints/main.go' ↓

cause The plugin tries to generate a main.go for module function handlers but the directory does not exist or is not writable.

fix

Manually create the generatedEntrypoints directory in your project root, or change the path via custom.go-build.generatedMainPath.

error Error: No handler given. Please define a valid handler. ↓

cause The function handler in serverless.yml does not match an existing .go file or a valid module.Function.

fix

Ensure the handler value points to an existing .go file (e.g., main.go) or a module function (e.g., packageName.FunctionName) with a generated main.go.

error Error: go build command failed with exit code 1 ↓

cause The Go source code has compilation errors or the build command is misconfigured.

fix

Check your Go files for syntax errors and verify custom.go-build.buildCmd and custom.go-build.awsbuildPrefix are correct for your environment.

Warnings

breaking Plugin only supports Serverless v1.x; incompatible with v2/v3. ↓

fix Use alternative plugin or stay on Serverless v1.x.

gotcha Build must be run explicitly with `serverless build` before `serverless deploy`; deploy does not auto-build. ↓

fix Run `serverless build` prior to `serverless deploy` or configure a deploy hook.

deprecated Plugin uses deprecated GOOS prefix `GOOS=linux ` which may not work on all shells. ↓

fix Override awsbuildPrefix with a safer value like `GOOS=linux` (without trailing space) or set it to empty string.

gotcha When specifying a module function handler (e.g., piece.GetPiece), the plugin generates a main.go file; ensure the package is importable and the generated path is writable. ↓

fix Check generatedEntrypoints directory and ensure module path is correct in custom.go-build.pathToAWSLambda.

Install

npm install serverless-go-build

yarn add serverless-go-build

pnpm add serverless-go-build

Imports

serverless-go-build
wrong
```
plugins:
  - serverless-go-build@0.0.6
```
correct
```
plugins:
  - serverless-go-build
```
Plugin is added to serverless.yml plugins list; no JavaScript import needed.
custom.go-build
wrong
```
custom:
  go-build:
    binPath: './bin'
```
correct
```
custom:
  go-build:
    binPath: 'bin'
```
Configuration is placed under custom.go-build in serverless.yml; relative paths are relative to project root without './'.
handler
wrong
```
functions:
  myFunc:
    handler: ./main.go
```
correct
```
functions:
  myFunc:
    handler: main.go
```
Handler value can be a .go file path (relative to project) or a module.Function name; no leading './'.

Quickstart

Install plugin, configure serverless.yml with Go handler, create main.go Lambda function, build and deploy.

npm install --save serverless-go-build

# serverless.yml
service: myService
plugins:
  - serverless-go-build
custom:
  go-build:
    binPath: bin
provider:
  name: aws
  runtime: go1.x
package:
  individually: true
functions:
  hello:
    handler: main.go
    name: myService-dev-hello
    events:
      - http:
          path: hello
          method: get

# main.go (in root)
package main

import "github.com/aws/aws-lambda-go/lambda"

func main() {
  lambda.Start(HandleRequest)
}

func HandleRequest() (string, error) {
  return "Hello from Go!", nil
}

# build and deploy
serverless build
serverless deploy