Static Asset Hashing in Hakyll
A problem I encountered while working on this website is that when I edit one of the CSS files and publish my changes to the Internet, there’s a good chance your browser will have cached the previous CSS files that it served you, and you won’t see the new styles that I have written.
To mitigate this, I decided to hack the compilation step in Hakyll so that my stylesheets are concatenated together, compressed, and then turned into an MD5 hash. This hash is then used as the path to the resulting file which forces the browser to download the new file whenever I update the styles.
The first step is to list the filepaths of the CSS files that should be compiled. The order in which rules are declared in CSS is important, so I prefer to list these filepaths explicitly.
-- | All CSS files which should be compiled styleSheets :: [FilePath] = styleSheets "css/normalize.css" [ "css/default.css" , "css/syntax.css" , ]
Next, we need to generate the MD5 hash for the compiled CSS file’s ultimate
filepath. By leveraging Hakyll’s
preprocess function, it’s possible to run
some arbitrary IO effects during the site’s compilation step.
The approach here is to:
- Read the contents of each CSS file.
- Concatenate the CSS files into one big string with
- Compress the string with Hakyll’s default
- Pack the string into a lazy bytestring, and build an MD5 digest with the
- Convert the MD5 digest back into a filepath and return it.
main :: IO () = hakyllWith config $ do main <- preprocess $ do compiledStylesheetPath <- mapM readFile styleSheets styles let h = md5 $ fromStrict $ pack $ compressCss $ mconcat styles pure $ "css/" <> show h <> ".css" let cssPathCtx = constField "cssPath" compiledStylesheetPath -- …
cssPathCtx binding is a convenience. It’s handy because most pages that
Hakyll generates will want CSS applied, which means most pages will need to
know where to find the compiled stylesheet.
Continuing on in our
Rules monad, we need to add a rule that generates the
file at the filepath we calculated in the preprocessing step. The route to this
file is already correct, so we keep it as is with
route idRoute. In the
compilation step for this rule, we are again loading our list of CSS filepaths
and adding them to some page context. The context here is only used in a
special file that we’ll use in a moment to render all of the CSS.
main :: IO () = hakyllWith config $ do main -- … $ do create [fromFilePath compiledStylesheetPath] route idRoute$ do compile <- mapM (load . fromFilePath) styleSheets styles let ctx = listField "styles" pageCtx (pure styles) "" >>= loadAndApplyTemplate "templates/all.css" ctx makeItem -- …
The snippet above references a template which doesn’t exist yet. We create that
file, and add a single line of Hakyll’s templating DSL to render all of the
contents of each of the CSS files by iterating over the
styles context we
At this point, the compiled stylesheet is being generated correctly, but the
site’s outermost template layer doesn’t reference it yet. Any time you load and
apply the outermost template layer — in this case called
templates/default.html — you’ll need to pass in the
earlier, likely monoidally joined with some other context for that template.
main :: IO () = hakyllWith config $ do main -- … "index.html" $ do match route idRoute$ do compile let ctx = cssPathCtx <> someOtherCtx getResourceBody>>= applyAsTemplate (field "posts" (const (recentPostList 3))) >>= loadAndApplyTemplate "templates/default.html" ctx >>= cleanIndexUrls -- …
Now that the default template knows the path to the compiled CSS file, we can update that reference.
<!DOCTYPE html> <html> <head> <title>$title$</title> <link rel="stylesheet" type="text/css" href="/$cssPath$" /> </head> <body> <!-- etc … -->
Everything works as expected when compiling the site from scratch, but a
typical development workflow involves running Hakyll’s filesystem monitor to
watch for changes and incrementally recompile the site. If you run the
command from your compiled Hakyll application binary and change one of the
stylesheets, the files referencing the compiled stylesheet don’t yet know that
they also need to be recompiled to reflect the new stylesheet path.
Fortunately, Hakyll provides some building blocks for declaring extra dependencies in rules. Here’s the final necessary change.
main :: IO () = hakyllWith config $ do main -- … "index.html" $ do match route idRoute<- makePatternDependency "css/*" dep $ compile $ do rulesExtraDependencies [dep] let ctx = cssPathCtx <> someOtherCtx getResourceBody>>= applyAsTemplate (field "posts" (const (recentPostList 3))) >>= loadAndApplyTemplate "templates/default.html" ctx >>= cleanIndexUrls -- …
Now during local development the outermost template layer will always reference the correct compiled stylesheet.
An added benefit of this approach is the concatenation step, which results in only a single HTTP request necessary to fetch all of the styles on page load.
This approach is working nicely on this website. If there’s a neater way to do it, please let me know.