Using Eleventy's RSS Plugin with the Eleventy Vite Plugin

tl;dr: If you are using Vite in conjunction with Eleventy's RSS plugin (using the virtual template option), make sure you are writing your feed.xml file to whatever your /public directory is or it won't get copied over to your production build. It will be present when you're running the dev server, which is why this is gotcha-esque. At the end of the day, remember, it's just pure Vite and Rollup passed through Eleventy.

And now for some vaguely useful rambling.

This site is built with Eleventy, which is currently a very popular static site generator ( SSG). The site is the first serious thing I've built using Eleventy, and I can reiterate what most people say about it – it's pretty fantastic. Static site generators are typically the next step in anyone's "I just want a simple HTML website" journey once they've repeated themselves one too many times. You just want to write HTML or Markdown but still enjoy all the abstractions of a templating language with maybe some routing and entry metadata thrown in. What about asynchronous external data? You got it.

Oh no. I guess it's time to do what every person who is trying to avoid actually shipping something does – write your own static site generator! Wait no, please don't do that. I did that once; it used Grunt and Swig templates. Remember Swig templates? Like Twig, but for Node? Of course you don't. Sort of like what Jinja is for Python, the JS version of which is Nunjucks, which closely resembles Twig. None of this is to be confused with Mustache templates, which are related to, but not the same as, Handlebars. See, not confusing at all. Web development is easy, you barely need to remember anything.

Anyway, yes, I've seen a lot of SSGs in my time ... Jekyll, Hugo, Assemble, Hexo, Flask ... wait does Flask count? I've even worked with Movable Type, which I think if you're being really pedantic about it, was a Perl-based SSG. The most successful SSGs seem to find the right balance between not doing enough and doing too much. Eleventy strikes that balance very well, and because of some confluence of Node-based JavaScript having reached a magical level of maturity ( Modules! Async!), Eleventy really shines in the right ways at the right time. It's also maintained by some really solid and conscientious people.

Beyond that, Eleventy knows how to get out of the way. It's essentially a compilation pipeline with one job, and it doesn't really want to have opinions about anything else you might want to do as part of that compilation pipeline. It does provide an API for middleware, though, so if you want to hitch some additional functionality or transformations on to the input as it goes on its magical journey to becoming output, you can do that.

I'm sorry for reducing your creative endeavors to merely input and output, I'm sure they are much more than that. Truly.

In relation to the point about Eleventy not caring about things it doesn't need to care about, it doesn't really have a concept of an asset pipeline, which is great. I don't want it to care about my assets. How I end up with the CSS and JS I want to ship is entirely my business. Personally, I use Vite for that sort of thing. This isn't a post about Vite, but the summary is that Vite is an extremely fast asset bundler that gives you a hot relaoding dev server for when you're devving, and an enterprise-grade production bundle when you're uh, productioning.

On the topic of tools not involving themselves with things they aren't good at, Vite is notable because for production builds, it essentially passes your inputs straight to Rollup, which if you know how engineers are, is a truly honorable act of deference to a tool that already does one thing well. So, just like Eleventy, Vite knows what it is good at and doesn't really need to know much about anything else. Like, it's 2024 and we're all finally maybe getting Demeter's Law – or the pinciple of least responsibility, or whatever it is. I mostly just wanted you to know that I know who Demeter is.

Anyway, you can use Vite as middleware with Eleventy via the eleventy-vite-plugin, which allows Vite and Eleventy's dev servers to work in tandem while you're devving, and allows your Vite bundled assets to be processed along with the production HTML generated by Eleventy when you're prductioning. The plugin is smart enough to understand your own particular project's concepts of input and output from the dir property in your Eleventy config, so in most cases, you can use the plugin with zero configuration.

The barest of configs would be something like:

// eleventy.config.js

import EleventyVitePlugin from '@11ty/eleventy-plugin-vite';

export default async function(eleventyConfig) {
  eleventyConfig.addPlugin(EleventyVitePlugin);

  // Ensure Eleventy understands and copies Vite's public directory.
  eleventyConfig.addPassthroughCopy('public');

  // Ensure Eleventy knows about your Vite-processed assets.
  eleventyConfig.addPassthroughCopy('src/assets/styles');
  eleventyConfig.addPassthroughCopy('src/assets/scripts');
}

/* And since I have an aversion to underscores, I change my default output
directory from `_site` to `dist`. */
export const config = {
  dir: {
    input: 'src',
    output: 'dist',
  },
};

Because Vite is acting as middleware here, you can also pass a full configuration object to Vite like you would in any old Vite project via the viteOptions property within the plugin options.

For example:

import EleventyVitePlugin from '@11ty/eleventy-plugin-vite';

export default async function(eleventyConfig) {
  eleventyConfig.addPlugin(EleventyVitePlugin, {
    viteOptions: {} // A whole ass Vite config goes here.
  });
}

And because it's middleware all the way down at this point, if you need a special Rollup config for Vite, you simply add that to your Vite options like you would in any old Vite project outside of Eleventy.

If there's a downside to the principle of least responsibility in terms of software, it's that the consumer can sometimes forget that they retain the responsibility for making certain things happen. Eleventy is great about not caring about things it doesn't need to care about, but that also means that you have to explicitly tell it a few things you may not be accustomed to needing to specify. This has already come up to some extent in this post with regard to making sure Eleventy knows about your compiled assets. It came up for me when using the official RSS plugin with Vite, and it wasn't immediately obvious what the issue was.

This isn't really a post about the plugin itself. The plugin is a really handy way to turn an Eleventy collection into an RSS feed. The newest version of the plugin allows you to specify and configure a collection to be turned into a feed, and also allows you to generate the build output for this feed via a virtual template. You can also manually create a template that contains all the properties and fields you need, but unless you need something super custom, the virtual template emits a feed file with a bunch of sensible defaults, and it's rad.

The configuration is pretty self documenting. Mine looks like this:

  eleventyConfig.addPlugin(feedPlugin, {
  type: 'atom',
  outputPath: '/public/feed.xml',
  collection: {
    name: 'posts',
    limit: 10,
  },
  metadata: {
    language: 'en',
    title: 'frgmnt.art',
    subtitle: 'An Audio Sketchbook',
    base: 'https://frgmnt.art/',
    author: {
      name: 'Ted Flynn',
      email: 'lolnope',
    },
  },
});

That is all it takes to generate an RSS feed of this site's posts collection. The feed file itself is ultimately available at https://frgmnt.art/feed.xml. The only real difference between that configuration and the one in the documentation is the outputPath value. In the docs, it's just /feed.xml, which I sort of expected to "just work", and it did to some extent, because while running the dev server, the feed is actually available at the site root.

This took a minute to realize and troubleshoot, because it wasn't immediately apparent what part of the chain wasn't picking the file up and copying it over into the build directory. I haven't tested this, but I imagine that the defualt configuration from the docs may work out of the box if you aren't using Vite. Nevertheless, the (potentially somewhat obvious) fix is to emit the file to your public directory in order to make Vite aware of it: outputPath: '/public/feed.xml'. With that change, Vite's own sort of passthrough behavior kicks in, and the file will be emitted in your production buld. Cool.

Another quick tip in relation to this is that you should probably always validate your production build locally before deploying. What's that? How did I know my RSS feed wasn't working? Of course I tested locally first ... ahem.

I'm sure everyone already knows this and it has been posted in a trillion tutorials, but here it is again. After all, Eleventy just outputs a static site, so all you need is an http server. For me that's:

npx @11ty/eleventy
cd dist
npx http-server .

Head on over to localhost:8080. That port might already be in use by your Eleventy dev server if you haven't stopped it before doing this. So, you know, stop your Eleventy dev server beforehand.

Thanks for reading this far if you did indeed get this far. Here's to another day of outputting inputs.