---
name: "Plack::Middleware::Static"
section: "3pm"
platform: "linux"
package: "libplack-perl"
version: "1.0051-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Plack::Middleware::Static"
---

# Plack::Middleware::Static(3pm)

serve static files with Plack

## NAME

Plack::Middleware::Static - serve static files with Plack

## SYNOPSIS

```
  use Plack::Builder;
  builder {
      enable "Plack::Middleware::Static",
          path => qr{^/(images|js|css)/}, root => './htdocs/';
      $app;
  };
```

## DESCRIPTION

This middleware allows your Plack-based application to serve static files.

Note that if you are building an app using Plack::App::URLMap, you should consider using Plack::App::File to serve static files instead. This makes the overall routing of your application simpler to understand.

With this middleware, if a static file exists for the requested path, it will be served. If it does not exist, by default this middleware returns a 404, but you can set the `"pass_through"` option to change this behavior.

If the requested document is not within the `"root"` or the file is there but not readable, this middleware will return a 403 Forbidden response.

The content type returned will be determined from the file extension by using Plack::MIME or using `"content_type"`.

## CONFIGURATIONS

- path, root

  ```
    enable "Plack::Middleware::Static",
        path => qr{^/static/}, root => 'htdocs/';
  ```

  The `"path"` option specifies the URL pattern (regular expression) or a callback to match against requests. If the \<path\> option matches, the middleware looks in `"root"` to find the static files to serve. The default value of `"root"` is the current directory.

  This example configuration serves `"/static/foo.jpg"` from `"htdocs/static/foo.jpg"`. Note that the matched portion of the path, `"/static/"`, still appears in the locally mapped path under `"root"`. If you don't want this to happen, you can use a callback to munge the path as you match it:

  ```
    enable "Plack::Middleware::Static",
        path => sub { s!^/static/!! }, root => 'static-files/';
  ```

  The callback should operate on `$_` and return a true or false value. Any changes it makes to `$_` are used when looking for the static file in the `"root"`.

  The configuration above serves `"/static/foo.png"` from `"static-files/foo.png"`, not `"static-files/static/foo.png"`. The callback specified in the `"path"` option matches against `$_` munges this value using `"s///"`. The substitution operator returns the number of matches it made, so it will return true when the path matches `"^/static"`.

  For more complex static handling in the `"path"` callback, in addition to `$_` being set the callback receives two arguments, `"PATH_INFO"` (same as `$_`) and `$env`.

  If you want to map multiple static directories from different roots, simply add this middleware multiple times with different configuration options.

- pass\_through

  When this option is set to a true value, then this middleware will never return a 404 if it cannot find a matching file. Instead, it will simply pass the request on to the application it is wrapping.

- content\_type

  The `"content_type"` option can be used to provide access to a different MIME  database than Plack::MIME. Plack::MIME works fast and good for a list of well known file endings,  but if you need a more accurate content based checking you can use modules like File::MimeInfo or File::MMagic for example. The callback should work on `$_`\[0\] which is the filename of the file.

## AUTHOR

Tokuhiro Matsuno, Tatsuhiko Miyagawa

## SEE ALSO

Plack::Middleware Plack::Builder