Skip to content

Document serving static files #39

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.

Sign up for GitHub

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

Open
Babali42 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Document serving static files #39

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c7fe14f
Documentation : Move response into a folder
Babali42 Jan 28, 2026
8a88baa
Documentation : Add static responses
Babali42 Jan 28, 2026
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
2 changes: 1 addition & 1 deletion docs/src/pages/controller/route/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ route.handle(userId => s"You asked for user $userId")

Notice that adding a handler produces a value with a different type, a @:api(krop.route.Handler).

For more details see the separate pages for [Request](request.md), [Response](response.md) and [Handler](../handler.md).
For more details see the separate pages for [Request](request.md), [Response](response/README.md) and [Handler](../handler.md).



Expand Down
4 changes: 2 additions & 2 deletions docs/src/pages/controller/route/response.md → ...pages/controller/route/response/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ You usually won't do this yourself; it is handled by the `Route` the `Response`

## Entities

Entities (response bodies) are handled in the same way as [requests](request.md): by specifying an @:api(krop.route.Entity). In this case the `Entity` is responsible for encoding Scala values as data in the HTTP response.
Entities (response bodies) are handled in the same way as [requests](../request.md): by specifying an @:api(krop.route.Entity). In this case the `Entity` is responsible for encoding Scala values as data in the HTTP response.

Use `Entity.unit` to indicate that your response has no entity. For example:

Expand Down Expand Up @@ -60,7 +60,7 @@ val getUser =
)
```

For more complex cases you can use `orElse`, which allows you to handle an `Either[A, B]` and introduce custom error handling. The example below shows complex error handling combining `orElse` and `orNotFound`. A 404 Not Found is returned if the user id does not correspond to an existing user, and a 400 Bad Request is returned if the `Name` [entity](entities.md) is not valid.
For more complex cases you can use `orElse`, which allows you to handle an `Either[A, B]` and introduce custom error handling. The example below shows complex error handling combining `orElse` and `orNotFound`. A 404 Not Found is returned if the user id does not correspond to an existing user, and a 400 Bad Request is returned if the `Name` [entity](../entities.md) is not valid.

```scala mdoc:silent
import io.circe.{Decoder, Encoder}
Expand Down
57 changes: 57 additions & 0 deletions docs/src/pages/controller/route/response/static.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# Static responses

Krop provides several Response constructors for serving static content. These differ in where the content is loaded from and in the type of value the route handler must return.

## StaticResource

StaticResource responds with a file loaded from the application’s classpath (resources). Files are resolved using the JVM classloader.

The pathPrefix is the resource directory, and the handler returns the remaining resource name.

```scala
val staticResourceHandleableRoute =
Route(
Request.get(Path / "kroptest" / "assets"),
Response.staticResource("/kroptest/assets/")
).handle(() => "create.html")
```

In this example, a request to /kroptest/assets will respond with the resource
/kroptest/assets/create.html.

Only resources available on the classpath can be served. Files added to the filesystem at runtime are not visible.

## StaticFile

StaticFile responds with a single file loaded from the filesystem.

The file path is fixed when the response is defined, and no handler input is required.

```scala
val staticFileRoute =
Route(
Request.get(Path / "kroptest" / "assets" / "create.html"),
Response.staticFile("resources/kroptest/assets/create.html")
).passthrough
```


In this example, a request to /kroptest/assets/create.html will read the file
resources/kroptest/assets/create.html from disk.

## StaticDirectory

StaticDirectory responds with files loaded from a filesystem directory. The handler determines which file inside the directory is served.

The pathPrefix parameter specifies the base directory, and the handler returns a relative Fs2Path within that directory.

```scala
val staticDirectoryRoute =
Route(
Request.get(Path / "kroptest" / "assets2" / Param.string),
Response.StaticDirectory(Fs2Path("resources/kroptest/assets"))
).handle(Fs2Path(_))
```

In this example, a request to /kroptest/assets2/create.html will read the file
resources/kroptest/assets/create.html from disk.