Skip to content

Commit

Permalink
Add docs from gofiber/fiber@38fb806
Browse files Browse the repository at this point in the history
  • Loading branch information
@github-actions
github-actions[bot] committed May 28, 2024
1 parent 8d7b3a9 commit f3e51ee
Show file tree
Hide file tree
Showing 5 changed files with 252 additions and 88 deletions.
66 changes: 0 additions & 66 deletions docs/core/api/app.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,70 +11,6 @@ import Reference from '@site/src/components/reference';

import RoutingHandler from './../partials/routing/handler.md';

### Static

Use the **Static** method to serve static files such as **images**, **CSS,** and **JavaScript**.

:::info
By default, **Static** will serve `index.html` files in response to a request on a directory.
:::

```go title="Signature"
func (app *App) Static(prefix, root string, config ...Static) Router
```

Use the following code to serve files in a directory named `./public`

```go title="Examples"
// Serve files from multiple directories
app.Static("/", "./public")

// => http://localhost:3000/hello.html
// => http://localhost:3000/js/jquery.js
// => http://localhost:3000/css/style.css

// Serve files from "./files" directory:
app.Static("/", "./files")
```

You can use any virtual path prefix \(_where the path does not actually exist in the file system_\) for files that are served by the **Static** method, specify a prefix path for the static directory, as shown below:

```go title="Examples"
app.Static("/static", "./public")

// => http://localhost:3000/static/hello.html
// => http://localhost:3000/static/js/jquery.js
// => http://localhost:3000/static/css/style.css
```

#### Config

If you want to have a little bit more control regarding the settings for serving static files. You could use the `fiber.Static` struct to enable specific settings.

| Property | Type | Description | Default |
|------------------------------------------------------------|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|
| <Reference id="compress">Compress</Reference> | `bool` | When set to true, the server tries minimizing CPU usage by caching compressed files. This works differently than the [compress](../middleware/compress.md) middleware. | false |
| <Reference id="byte_range">ByteRange</Reference> | `bool` | When set to true, enables byte range requests. | false |
| <Reference id="browse">Browse</Reference> | `bool` | When set to true, enables directory browsing. | false |
| <Reference id="download">Download</Reference> | `bool` | When set to true, enables direct download. | false |
| <Reference id="index">Index</Reference> | `string` | The name of the index file for serving a directory. | "index.html" |
| <Reference id="cache_duration">CacheDuration</Reference> | `time.Duration` | Expiration duration for inactive file handlers. Use a negative `time.Duration` to disable it. | 10 * time.Second |
| <Reference id="max_age">MaxAge</Reference> | `int` | The value for the `Cache-Control` HTTP-header that is set on the file response. MaxAge is defined in seconds. | 0 |
| <Reference id="modify_response">ModifyResponse</Reference> | `Handler` | ModifyResponse defines a function that allows you to alter the response. | nil |
| <Reference id="next">Next</Reference> | `func(c Ctx) bool` | Next defines a function to skip this middleware when returned true. | nil |

```go title="Example"
// Custom config
app.Static("/", "./public", fiber.Static{
Compress: true,
ByteRange: true,
Browse: true,
Index: "john.html",
CacheDuration: 10 * time.Second,
MaxAge: 3600,
})
```

### Route Handlers

<RoutingHandler />
Expand Down Expand Up @@ -181,8 +117,6 @@ type Register interface {

Add(methods []string, handler Handler, middleware ...Handler) Register

Static(root string, config ...Static) Register

Route(path string) Register
}
```
Expand Down
27 changes: 15 additions & 12 deletions docs/core/api/constants.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,24 +26,27 @@ const (

```go
const (
MIMETextXML = "text/xml"
MIMETextHTML = "text/html"
MIMETextPlain = "text/plain"
MIMEApplicationXML = "application/xml"
MIMEApplicationJSON = "application/json"
MIMETextXML = "text/xml"
MIMETextHTML = "text/html"
MIMETextPlain = "text/plain"
MIMETextJavaScript = "text/javascript"
MIMETextCSS = "text/css"
MIMEApplicationXML = "application/xml"
MIMEApplicationJSON = "application/json"
MIMEApplicationJavaScript = "application/javascript"
MIMEApplicationForm = "application/x-www-form-urlencoded"
MIMEOctetStream = "application/octet-stream"
MIMEMultipartForm = "multipart/form-data"

MIMETextXMLCharsetUTF8 = "text/xml; charset=utf-8"
MIMETextHTMLCharsetUTF8 = "text/html; charset=utf-8"
MIMETextPlainCharsetUTF8 = "text/plain; charset=utf-8"
MIMEApplicationXMLCharsetUTF8 = "application/xml; charset=utf-8"
MIMEApplicationJSONCharsetUTF8 = "application/json; charset=utf-8"
MIMETextXMLCharsetUTF8 = "text/xml; charset=utf-8"
MIMETextHTMLCharsetUTF8 = "text/html; charset=utf-8"
MIMETextPlainCharsetUTF8 = "text/plain; charset=utf-8"
MIMETextJavaScriptCharsetUTF8 = "text/javascript; charset=utf-8"
MIMETextCSSCharsetUTF8 = "text/css; charset=utf-8"
MIMEApplicationXMLCharsetUTF8 = "application/xml; charset=utf-8"
MIMEApplicationJSONCharsetUTF8 = "application/json; charset=utf-8"
MIMEApplicationJavaScriptCharsetUTF8 = "application/javascript; charset=utf-8"
)
```
)```
### HTTP status codes were copied from net/http.
Expand Down
8 changes: 2 additions & 6 deletions docs/core/intro.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -164,19 +164,15 @@ app.Get("/api/*", func(c fiber.Ctx) error {
### Static files

To serve static files such as **images**, **CSS**, and **JavaScript** files, replace your function handler with a file or directory string.

You can check out [static middleware](./middleware/static.md) for more information.
Function signature:

```go
app.Static(prefix, root string, config ...Static)
```

Use the following code to serve files in a directory named `./public`:

```go
app := fiber.New()

app.Static("/", "./public")
app.Get("/*", static.New("./public"))

app.Listen(":3000")
```
Expand Down
172 changes: 172 additions & 0 deletions docs/core/middleware/static.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,172 @@
---
id: static
---

# Static

Static middleware for Fiber that serves static files such as **images**, **CSS,** and **JavaScript**.

:::info
By default, **Static** will serve `index.html` files in response to a request on a directory. You can change it from [Config](#config)`
:::

## Signatures

```go
func New(root string, cfg ...Config) fiber.Handler
```

## Examples

Import the middleware package that is part of the [Fiber](https://github.com/gofiber/fiber) web framework
```go
import(
"github.com/gofiber/fiber/v3"
"github.com/gofiber/fiber/v3/middleware/static"
)
```

### Serving files from a directory

```go
app.Get("/*", static.New("./public"))
```
<details>
<summary>Test</summary>
```sh
curl http://localhost:3000/hello.html
curl http://localhost:3000/css/style.css
```
</details>
### Serving files from a directory with Use
```go
app.Use("/", static.New("./public"))
```
<details>
<summary>Test</summary>
```sh
curl http://localhost:3000/hello.html
curl http://localhost:3000/css/style.css
```
</details>
### Serving a file
```go
app.Use("/static", static.New("./public/hello.html"))
```
<details>
<summary>Test</summary>
```sh
curl http://localhost:3000/static # will show hello.html
curl http://localhost:3000/static/john/doee # will show hello.html
```
</details>
### Serving files using os.DirFS
```go
app.Get("/files*", static.New("", static.Config{
FS: os.DirFS("files"),
Browse: true,
}))
```
<details>
<summary>Test</summary>
```sh
curl http://localhost:3000/files/css/style.css
curl http://localhost:3000/files/index.html
```
</details>
### Serving files using embed.FS
```go
//go:embed path/to/files
var myfiles embed.FS
app.Get("/files*", static.New("", static.Config{
FS: myfiles,
Browse: true,
}))
```
<details>
<summary>Test</summary>
```sh
curl http://localhost:3000/files/css/style.css
curl http://localhost:3000/files/index.html
```
</details>
### SPA (Single Page Application)
```go
app.Use("/web", static.New("", static.Config{
FS: os.DirFS("dist"),
}))
app.Get("/web*", func(c fiber.Ctx) error {
return c.SendFile("dist/index.html")
})
```
<details>
<summary>Test</summary>
```sh
curl http://localhost:3000/web/css/style.css
curl http://localhost:3000/web/index.html
curl http://localhost:3000/web
```
</details>
:::caution
To define static routes using `Get`, append the wildcard (`*`) operator at the end of the route.
:::
## Config
| Property | Type | Description | Default |
|:-----------|:------------------------|:---------------------------------------------------------------------------------------------------------------------------|:-----------------------|
| Next | `func(fiber.Ctx) bool` | Next defines a function to skip this middleware when returned true. | `nil` |
| FS | `fs.FS` | FS is the file system to serve the static files from.<br /><br />You can use interfaces compatible with fs.FS like embed.FS, os.DirFS etc. | `nil` |
| Compress | `bool` | When set to true, the server tries minimizing CPU usage by caching compressed files.<br /><br />This works differently than the github.com/gofiber/compression middleware. | `false` |
| ByteRange | `bool` | When set to true, enables byte range requests. | `false` |
| Browse | `bool` | When set to true, enables directory browsing. | `false` |
| Download | `bool` | When set to true, enables direct download. | `false` |
| IndexNames | `[]string` | The names of the index files for serving a directory. | `[]string{"index.html"}` |
| CacheDuration | `string` | Expiration duration for inactive file handlers.<br /><br />Use a negative time.Duration to disable it. | `10 * time.Second` |
| MaxAge | `int` | The value for the Cache-Control HTTP-header that is set on the file response. MaxAge is defined in seconds. | `0` |
| ModifyResponse | `fiber.Handler` | ModifyResponse defines a function that allows you to alter the response. | `nil` |
| NotFoundHandler | `fiber.Handler` | NotFoundHandler defines a function to handle when the path is not found. | `nil` |
:::info
You can set `CacheDuration` config property to `-1` to disable caching.
:::
## Default Config
```go
var ConfigDefault = Config{
Index: []string{"index.html"},
CacheDuration: 10 * time.Second,
}
```
Loading

0 comments on commit f3e51ee

Please sign in to comment.