Plack::...::Static(3)

💖 NAME 💖

Plack::Middleware::Static — bestie, this is the middleware that serves your static files with Plack ✨

It lives in the Plack family and it's part of the User Contributed Perl Documentation crowd, no cap 🫶

---

✨ SYNOPSIS ✨

okay so this is the whole vibe:

use Plack::Builder;

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

that's it. that's the whole thing. iconic 💅

---

🦋 DESCRIPTION 🦋

This middleware lets your Plack-based app serve static files. literally it just. does that. for you. 💖

ngl there's a little plot twist here — if you're building an app with Plack::App::URLMap, you should lowkey consider using Plack::App::File to serve static files instead. the reason is very main-character of it: it makes the overall routing of your application simpler to understand. do with that info what you will 🧚

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

And if the requested document is not within the root, or the file is there but not readable? 403 Forbidden bestie 😭 that's the answer. no file for you.

The content type returned will be determined from the file extension by using Plack::MIME, or by using content_type (we'll get to that, keep reading 🌸)

---

🎀 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 📁 (yes, the one you're standing in, bestie).

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. slay ✨

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 $_ and 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". the way that substitution operator doubles as a boolean is honestly so clever, ate 💀

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. two whole arguments, she's generous 🫶

If you want to map multiple static directories from different roots, simply add this middleware multiple times with different configuration options. stack 'em like jewelry 💅

⭐ 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. no drama, no rejection, just pass it along bestie 💜

🔥 content_type

The content_type option can be used to provide access to a different MIME database than Plack::MIME. Here's the tea: 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. yep, $_[0]. that's the one. that's your girl 🎀

---

👑 AUTHOR 👑

Tokuhiro Matsuno, Tatsuhiko Miyagawa

(legends. absolute icons. we stan 🫶)

---

💜 SEE ALSO 💜

• Plack::Middleware
• Plack::Builder

---

and that's the page bestie!! 💖 this was Plack::...::Static(3) from perl v5.42.3, dated 2026-10-18 🌸 go forth and serve those static files, you're doing amazing sweetie ✨💅🦋