Documentation
¶
Overview ¶
Package static serves static files from the OS filesystem or an fs.FS.
Use New with a Config to mount the middleware. Set Config.Root for an OS directory or Config.FS for an embedded/virtual filesystem (mutually exclusive; FS takes precedence when both are set). Key options:
- Config.Prefix — URL path prefix, matched at segment boundaries.
- Config.Index — directory index filename (default "index.html").
- Config.Browse — enable HTML directory listings.
- Config.SPA — single-page app mode: unknown paths serve the index file.
- Config.MaxAge — Cache-Control max-age duration (zero = no header).
- Config.Compress — serve pre-compressed .br/.gz variants when accepted.
- Config.Skip / Config.SkipPaths — skip the middleware dynamically or by exact path match.
Only GET and HEAD requests are processed; all others pass through. The middleware sets Last-Modified, ETag (weak, mtime+size), and optional Cache-Control headers and handles conditional requests (304 Not Modified).
Documentation ¶
Full guides and examples: https://goceleris.dev/docs/static-files
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func New ¶
func New(config ...Config) celeris.HandlerFunc
New creates a static file middleware with the given config.
Example ¶
package main
import (
"github.com/goceleris/celeris/middleware/static"
)
func main() {
// Serve files from an OS directory.
_ = static.New(static.Config{
Root: "./public",
})
}
Output:
Example (Browse) ¶
package main
import (
"github.com/goceleris/celeris/middleware/static"
)
func main() {
// Enable directory listing.
_ = static.New(static.Config{
Root: "./public",
Browse: true,
})
}
Output:
Example (Compress) ¶
package main
import (
"time"
"github.com/goceleris/celeris/middleware/static"
)
func main() {
// Serve pre-compressed files when available. If the client sends
// Accept-Encoding: br, the middleware serves app.js.br instead of
// app.js (and sets Content-Encoding: br). Falls back to the original
// file when no pre-compressed variant exists.
_ = static.New(static.Config{
Root: "./dist",
Compress: true,
MaxAge: 7 * 24 * time.Hour,
})
}
Output:
Example (EmbedFS) ¶
package main
import (
"embed"
"github.com/goceleris/celeris/middleware/static"
)
//go:embed doc.go
var embeddedFS embed.FS
func main() {
// Serve files from an embedded filesystem.
_ = static.New(static.Config{
FS: embeddedFS,
Prefix: "/assets",
})
}
Output:
Example (MaxAge) ¶
package main
import (
"time"
"github.com/goceleris/celeris/middleware/static"
)
func main() {
// Set a 24-hour Cache-Control max-age alongside the automatic ETag
// and Last-Modified headers.
_ = static.New(static.Config{
Root: "./public",
MaxAge: 24 * time.Hour,
})
}
Output:
Example (Spa) ¶
package main
import (
"github.com/goceleris/celeris/middleware/static"
)
func main() {
// Serve a single-page application: non-existent paths fall back to
// index.html so the client-side router can handle them.
_ = static.New(static.Config{
Root: "./dist",
SPA: true,
})
}
Output:
Types ¶
type Config ¶
type Config struct {
// Skip defines a function to skip this middleware for certain requests.
Skip func(c *celeris.Context) bool
// SkipPaths lists paths to skip (exact match).
SkipPaths []string
// Root is the directory path on the OS filesystem from which to serve
// files. Mutually exclusive with FS. If neither Root nor FS is set,
// the middleware panics.
Root string
// FS is an [fs.FS] from which to serve files (e.g. embed.FS).
// Mutually exclusive with Root. If both Root and FS are set, FS takes
// precedence.
FS fs.FS
// Prefix is the URL path prefix to strip before looking up the file.
// For example, Prefix: "/static" serves /static/style.css from style.css
// in Root/FS. The prefix is matched at segment boundaries: /static does
// not match /static-docs.
// Default: "/" (serve from the URL root).
Prefix string
// Index is the default file to serve when the request path resolves to
// a directory.
// Default: "index.html".
Index string
// Browse enables directory listing when the request path resolves to
// a directory without an index file.
// Default: false.
Browse bool
// SPA enables single-page application mode. When true, requests for
// non-existent files serve the index file instead of falling through
// to the next handler. Useful for single-page applications.
// Default: false.
SPA bool
// MaxAge sets the Cache-Control max-age directive. Zero means no
// Cache-Control header.
MaxAge time.Duration
// Compress enables serving pre-compressed files. When true, the middleware
// checks for .br (Brotli) and .gz (gzip) variants of the requested file
// and serves them if the client accepts the encoding via Accept-Encoding.
// Brotli is preferred over gzip when both are accepted. Works with both
// OS filesystem (Root) and fs.FS.
Compress bool
}
Config defines the static file middleware configuration.
Source Files
Click to show internal directories.
Click to hide internal directories.