Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

📚 Doc: Update intro documentation #3204

Merged
merged 1 commit into from
Nov 13, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 35 additions & 28 deletions docs/intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,15 @@ id: welcome
title: 👋 Welcome
sidebar_position: 1
---
An online API documentation with examples so you can start building web apps with Fiber right away!
Welcome to the online API documentation for Fiber, complete with examples to help you start building web applications with Fiber right away!

**Fiber** is an [Express](https://github.com/expressjs/express) inspired **web framework** built on top of [Fasthttp](https://github.com/valyala/fasthttp), the **fastest** HTTP engine for [Go](https://go.dev/doc/). Designed to **ease** things up for **fast** development with **zero memory allocation** and **performance** in mind.
**Fiber** is an [Express](https://github.com/expressjs/express)-inspired **web framework** built on top of [Fasthttp](https://github.com/valyala/fasthttp), the **fastest** HTTP engine for [Go](https://go.dev/doc/). It is designed to facilitate rapid development with **zero memory allocations** and a strong focus on **performance**.

These docs are for **Fiber v3**, which was released on **March XX, 2024**.
These docs are for **Fiber v3**, which was released on **Month xx, 202x**.

### Installation

First of all, [download](https://go.dev/dl/) and install Go. `1.22` or higher is required.
First, [download](https://go.dev/dl/) and install Go. Version `1.22` or higher is required.

Installation is done using the [`go get`](https://pkg.go.dev/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them) command:

Expand All @@ -22,7 +22,7 @@ go get github.com/gofiber/fiber/v3

### Zero Allocation

Fiber is optimized for **high-performance**, meaning values returned from **fiber.Ctx** are **not** immutable by default and **will** be re-used across requests. As a rule of thumb, you **must** only use context values within the handler and **must not** keep any references. Once you return from the handler, any values obtained from the context will be re-used in future requests. Here is an example:
Fiber is optimized for **high performance**, meaning values returned from **fiber.Ctx** are **not** immutable by default and **will** be reused across requests. As a rule of thumb, you **must** only use context values within the handler and **must not** keep any references. Once you return from the handler, any values obtained from the context will be reused in future requests. Here is an example:

```go
func handler(c fiber.Ctx) error {
Expand All @@ -44,13 +44,13 @@ func handler(c fiber.Ctx) error {
buffer := make([]byte, len(result))
copy(buffer, result)
resultCopy := string(buffer)
// Variable is now valid forever
// Variable is now valid indefinitely

// ...
}
```

We created a custom `CopyString` function that does the above and is available under [gofiber/utils](https://github.com/gofiber/utils).
We created a custom `CopyString` function that performs the above and is available under [gofiber/utils](https://github.com/gofiber/utils).

```go
app.Get("/:foo", func(c fiber.Ctx) error {
Expand All @@ -61,19 +61,19 @@ app.Get("/:foo", func(c fiber.Ctx) error {
})
```

Alternatively, you can also use the `Immutable` setting. It will make all values returned from the context immutable, allowing you to persist them anywhere. Of course, this comes at the cost of performance.
Alternatively, you can enable the `Immutable` setting. This makes all values returned from the context immutable, allowing you to persist them anywhere. Note that this comes at the cost of performance.

```go
app := fiber.New(fiber.Config{
Immutable: true,
})
```

For more information, please check [**\#426**](https://github.com/gofiber/fiber/issues/426), [**\#185**](https://github.com/gofiber/fiber/issues/185) and [**\#3012**](https://github.com/gofiber/fiber/issues/3012).
For more information, please refer to [#426](https://github.com/gofiber/fiber/issues/426), [#185](https://github.com/gofiber/fiber/issues/185), and [#3012](https://github.com/gofiber/fiber/issues/3012).

### Hello, World

Embedded below is essentially the most straightforward **Fiber** app you can create:
Below is the most straightforward **Fiber** application you can create:

```go
package main
Expand All @@ -95,15 +95,15 @@ func main() {
go run server.go
```

Browse to `http://localhost:3000` and you should see `Hello, World!` on the page.
Browse to `http://localhost:3000` and you should see `Hello, World!` displayed on the page.

### Basic routing
### Basic Routing

Routing refers to determining how an application responds to a client request to a particular endpoint, which is a URI (or path) and a specific HTTP request method (`GET`, `PUT`, `POST`, etc.).
Routing determines how an application responds to a client request to a particular endpoint, which is a URI (or path) and a specific HTTP request method (`GET`, `PUT`, `POST`, etc.).

Each route can have **multiple handler functions** that are executed when the route is matched.

Route definition takes the following structures:
Route definitions follow the structure below:

```go
// Function signature
Expand All @@ -115,10 +115,10 @@ app.Method(path string, ...func(fiber.Ctx) error)
- `path` is a virtual path on the server
- `func(fiber.Ctx) error` is a callback function containing the [Context](https://docs.gofiber.io/api/ctx) executed when the route is matched

#### Simple route
#### Simple Route

```go
// Respond with "Hello, World!" on root path, "/"
// Respond with "Hello, World!" on root path "/"
app.Get("/", func(c fiber.Ctx) error {
return c.SendString("Hello, World!")
})
Expand All @@ -131,21 +131,22 @@ app.Get("/", func(c fiber.Ctx) error {

app.Get("/:value", func(c fiber.Ctx) error {
return c.SendString("value: " + c.Params("value"))
// => Get request with value: hello world
// => Response: "value: hello world"
})
```

#### Optional parameter
#### Optional Parameter

```go
// GET http://localhost:3000/john

app.Get("/:name?", func(c fiber.Ctx) error {
if c.Params("name") != "" {
return c.SendString("Hello " + c.Params("name"))
// => Hello john
// => Response: "Hello john"
}
return c.SendString("Where is john?")
// => Response: "Where is john?"
})
```

Expand All @@ -156,27 +157,33 @@ app.Get("/:name?", func(c fiber.Ctx) error {

app.Get("/api/*", func(c fiber.Ctx) error {
return c.SendString("API path: " + c.Params("*"))
// => API path: user/john
// => Response: "API path: user/john"
})
```

### Static files
### 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:
To serve static files such as **images**, **CSS**, and **JavaScript** files, use the `Static` method with a directory path. For more information, refer to the [static middleware](./middleware/static.md).

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

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

import (
"github.com/gofiber/fiber/v3"
)

app.Get("/*", static.New("./public"))
func main() {
app := fiber.New()

app.Listen(":3000")
app.Static("/", "./public")

app.Listen(":3000")
}
```

Now, you can load the files that are in the `./public` directory:
Now, you can access the files in the `./public` directory via your browser:

```bash
http://localhost:3000/hello.html
Expand Down