Go client library for generating ImageBoss image URLs. Build URLs with operations (resize, cover, CDN), path-segment options, and optional signing.
go get github.com/imageboss/go
Create a URL builder with your ImageBoss source (configured in your dashboard), then build URLs with operations and options.
package main import ( "fmt" "github.com/imageboss/go" ) func main() { b, err := imageboss.NewURLBuilder("mywebsite-images") if err != nil { panic(err) } // CDN (pass-through, no resize) url := b.CreateURL("examples/02.jpg", imageboss.CDN()) fmt.Println(url) // https://img.imageboss.me/mywebsite-images/cdn/examples/02.jpg // Fixed width (proportional height) url = b.CreateURL("examples/02.jpg", imageboss.Width(700)) // https://img.imageboss.me/mywebsite-images/width/700/examples/02.jpg // Fixed height url = b.CreateURL("examples/02.jpg", imageboss.Height(700)) // Cover (exact dimensions, smart crop by default) url = b.CreateURL("examples/02.jpg", imageboss.Cover(300, 300)) // Cover with mode (center, smart, attention, entropy, face, north, etc.) url = b.CreateURL("examples/02.jpg", imageboss.CoverMode(320, 320, "center")) // With options (path-segment options) url = b.CreateURL("examples/02.jpg", imageboss.Width(700), imageboss.Blur(4), imageboss.FormatAuto()) // https://img.imageboss.me/mywebsite-images/width/700/blur:4/format:auto/examples/02.jpg }
imageboss.WithBaseURL("https://custom.cdn.example.com")– custom base URL.imageboss.WithHTTPS(false)– use HTTP (default: true).imageboss.WithSecret(secret)– sign URLs with abossTokenquery parameter (see Signed URLs).
For sources with signed URLs enabled in the ImageBoss dashboard, pass your secret when creating the builder. The library signs the URL path with HMAC SHA-256 and appends ?bossToken=<hex>.
b, err := imageboss.NewURLBuilder("mysecureimages", imageboss.WithSecret(os.Getenv("IMAGEBOSS_SECRET"))) if err != nil { panic(err) } url := b.CreateURL("images/photo.jpg", imageboss.Width(500)) // https://img.imageboss.me/mysecureimages/width/500/images/photo.jpg?bossToken=...
Fluid (width-based) srcset:
srcset := b.CreateSrcset("image.png", imageboss.CDN(), nil, imageboss.WithMinWidth(100), imageboss.WithMaxWidth(380), imageboss.WithTolerance(0.08)) // Use in HTML: <img srcset="..." sizes="...">
Custom widths:
srcset := b.CreateSrcsetFromWidths("image.jpg", imageboss.Width(100), nil, []int{100, 200, 300, 400})
Fixed dimensions (DPR-based, 1x–5x):
srcset := b.CreateSrcset("image.png", imageboss.Width(800), nil)
imageboss.TargetWidths(minWidth, maxWidth, tolerance)– list of target widths for custom srcsets.imageboss.MustNewURLBuilder(source, opts...)– panics on invalid source instead of returning an error.
- Operations:
cdn,width,height,cover(with optional mode:center,smart,attention,entropy,face,north, etc.). - Options (path segments): e.g.
blur:4,format:auto,download:1,fill-color:ffffff. Useimageboss.Opt("key", "value")or helpers likeimageboss.Blur(4),imageboss.FormatAuto(),imageboss.Download().
See ImageBoss docs for the full API.
go test ./...Run the example server to try URLs in the browser:
go run ./examples/playground
# Open http://127.0.0.1:8080/?source=YOUR_IMAGEBOSS_SOURCEOr print URLs from the basic example:
go run ./examples/basic
This repo uses Changesets for versioning and changelogs. Run npm install first so the changeset CLI is available.
- Add a changeset after making a change:
npm run changeset(choose bump type and add a summary). Commit and push tomain. - CI does the rest: On push to
main, the release workflow runs. If there were unreleased changesets, it runs the version bump, commits and pushes the updatedpackage.json,CHANGELOG.md, andbuilder.go, and creates and pushes the tag (e.g.v1.0.3). You don’t need to runreleaseortag:pushlocally. - Releasing without CI: If you’re not using the workflow, run
npm run releaselocally (it versions, commits, pushes tomain, and creates/pushes the tag), or donpm run changeset:version→ commit & push →npm run tag:push.
See .changeset/README.md for details.
See LICENSE in this repository.