Eleventy Serverless Documentation

[ajcwebdev]

Eleventy Serverless Documentation

A first pass at documenting how Eleventy Serverless is being utilized in showmy.chat. Suggested additions, reorganizations, corrections, or retractions are welcome and encouraged.

This will be continually evolving for the foreseeable future because the capabilities of showmy.chat will be expanding and Eleventy Serverless is still in current development as a v1.0.0-beta Eleventy feature and subject to change.

Outline

• Rendering Modes
• Serverless Bundler Plugin
• Serverless Function Handler

Introduction

This project utilizes Eleventy Serverless and Netlify Functions. Serverless function handlers are deployed and managed automatically by Netlify. An endpoint URL is exposed for taking requests and running JavaScript functions to return responses.

Rendering Modes

There are three different rendering modes provided by Eleventy Serverless with distinct capabilities and trade-offs. The Eleventy Serverless documentation provides the following descriptions and recommendations.

Mode	Description	When to use
Build template	Render in the build	The preferred mode, start here
On-demand Builder template	Render on first request	When your build gets beefy
Dynamic template	Render on every request	For newly possible use cases like accepting user input, search, authentication, and database access

Serverless Bundler Plugin

The EleventyServerlessBundlerPlugin is provided to eleventyConfig in the project's .eleventy.js configuration file. For the sake of explanation, here is what the configuration file would look like with the other, non-serverless plugins removed.

// .eleventy.js

const {EleventyServerlessBundlerPlugin} = require('@11ty/eleventy')

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(EleventyServerlessBundlerPlugin, {
    name: 'serverless',
    functionsDir: './netlify/functions',
    inputDir: './src',
    copy: ['src/themes/']
  })

  return {
    dir: {
      input: 'src'
    }
  }
}

The plugin specifies:

Option	Value	Description
name	serverless	The only required option is a name for the function.
functionsDir	./netlify/functions	The directory that holds your serverless functions. Netlify supports ./netlify/functions without configuration.
inputDir	./src	Eleventy input directory containing the project's templates.
copy	src/themes	An array containing extra files that need to be bundled with the serverless function, in this case CSS files of the chat themes.

Serverless Function Handler

The function itself is contained in the index.js file inside the netlify/functions/serverless directory. EleventyServerless is imported and given configuration options including the inputDir and functionsDir like in eleventyConfig.

An event object is passed for the URL path and query parameters. A name for the URL path is required, in this case event.path which uses the input received through the event object. Dynamic Templates provide query parameters available in the eleventy.serverless.query object that can be used to accept user input with event.queryStringParameters.

// netlify/functions/serverless/index.js

const {EleventyServerless} = require("@11ty/eleventy")
require("./eleventy-bundler-modules.js")

async function handler(event) {
  console.dir({
    path: event.path, ...event.queryStringParameters
  })

  let elev = new EleventyServerless("serverless", {
    path: event.path,
    query: event.queryStringParameters,
    inputDir: "./src",
    functionsDir: "./netlify/functions",
  })

  try {
    return { }
  } catch (error) { }
    return { }
  }
}

exports.handler = handler

If try...catch succeeds then body is set to elev.render() and a 200 status code is returned. If try...catch fails then body is set to error.message and a 500 status code is returned.

// netlify/functions/serverless/index.js

  try {
    return {
      statusCode: 200,
      headers: { "Content-Type": "text/html; charset=UTF-8" },
      body: await elev.render(),
    }
  } catch (error) {
    if (elev.isServerlessUrl(event.path)) {
      console.log("Serverless Error:", error)
    }

    return {
      statusCode: error.httpStatusCode || 500,
      body: JSON.stringify(
        {
          error: error.message,
        },
        null,
        2
      ),
    }
  }

Complete file.

// netlify/functions/serverless/index.js

const {EleventyServerless} = require("@11ty/eleventy")

require("./eleventy-bundler-modules.js")

async function handler(event) {
  console.dir({
    path: event.path, ...event.queryStringParameters
  })

  let elev = new EleventyServerless("serverless", {
    path: event.path,
    query: event.queryStringParameters,
    inputDir: "./src",
    functionsDir: "./netlify/functions",
  })

  try {
    return {
      statusCode: 200,
      headers: { "Content-Type": "text/html; charset=UTF-8" },
      body: await elev.render(),
    }
  } catch (error) {
    if (elev.isServerlessUrl(event.path)) {
      console.log("Serverless Error:", error)
    }

    return {
      statusCode: error.httpStatusCode || 500,
      body: JSON.stringify(
        {
          error: error.message,
        },
        null,
        2
      ),
    }
  }
}

exports.handler = handler

[BenDMyers]

@ajcwebdev This is a fantastic writeup! Thank you so much for putting this together.

I don't know if and how this could help with your mental model, but netlify/functions/serverless/index.js (really everything inside netlify/functions/serverless) was completely generated for us by the EleventyServerlessBundlerPlugin. The only edit I've made since generating it was cleaning up some comments and adding the console.dir({path: event.path, ...event.queryStringParameters}).

We're free to mess with our netlify/functions/serverless/index.js as much as we need - and I think this would be a great place to validate our query parameters before Eleventy ever sees them.