Document serverless and dynamic content configurations

[noelforte]

I'm following the Serverless documentation and am struggling to understand if I should be passing the bundler options as an object when invoking addPlugin(EleventyServerlessBundlerPlugin):

// ...config stuff...

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

eleventyConfig.addPlugin(EleventyServerlessBundlerPlugin, {
  name: "possum",
  functionsDir: "./netlify/functions/",
  redirects: "netlify-toml",
  copy: [{ from: .cache, to: cache}],
  config: function (serverlessConfig) {
    serverlessConfig.addGlobalData("home", "tree");
    serverlessConfig.addGlobalData("possom-cookies", event.headers.cookie);
  }
});

// ...rest of config...

...or...

if I should be only passing name and functionsDir as options, let Eleventy do the bundle and then add any remaining options after the serverless function has been generated to index.js:

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

// Explicit dependencies for the bundler from config file and global data.
// The file is generated by the Eleventy Serverless Bundler Plugin.
require('./eleventy-bundler-modules.js');

async function handler(event) {
  let elev = new EleventyServerless('serverless', {
    path: new URL(event.rawUrl).pathname,
    query: event.multiValueQueryStringParameters || event.queryStringParameters,
    functionsDir: './netlify/functions/',
    redirects: "netlify-toml",
    copy: [{ from: .cache, to: cache}],
    config: function (eleventy) {
      serverlessConfig.addGlobalData("home", "tree");
      serverlessConfig.addGlobalData("possom-cookies", event.headers.cookie);
    },
  });

// ...rest of serverless function...

---

If the latter is the way to do it, should the docs clairify that what are currently labeled as "bundler options" are in fact "serverless function options" and should be placed in the function after it has been bundled rather than in the configuration for the bundler?

The documentation indicates that options passed on the call to addPlugin(EleventyServerlessBundlerPlugin) is the correct way to set up Serverless functionality, like in my first example. However, adding a config key and corresponding function to the eleventy config doesn't add the function to the serverless function when bundled—I have to add it myself in order for my addGlobalData() calls to work correctly.

As an example, this code in my eleventy.config.js...

// Serverless
eleventy.addPlugin(EleventyServerlessBundlerPlugin, {
  name: 'dynamic',
  functionsDir: './netlify/functions/',
  redirects: 'netlify-toml',
  config: function (eleventy) {
    eleventy.addGlobalData('cookie', event.headers.cookie);
  },
  copyEnabled: false,
});

...generates this in ./netlify/functions/dynamic/index.js:

async function handler(event) {
  let elev = new EleventyServerless("dynamic", {
    path: new URL(event.rawUrl).pathname,
    query: event.multiValueQueryStringParameters || event.queryStringParameters,
    functionsDir: "./netlify/functions/",
    // missing config: [...], needs to be added in manually
  });

// ...rest of function code...
}

The documentation goes on to point out that once the function has been bundled by Eleventy, the resulting code is managed by the user which would seem to suggest that some configuration takes place post-bundle as shown in my second example. If that's the case, should the docs clarify the purpose of maintaining a configuration in eleventy.config.js in addition to the bundled function?

Lastly, in my experimentation, I've also noticed that Eleventy doesn't modify the function directory on subsequent builds (like if files are removed, or if the configuration is changed to stop files from being copied over, it seems like the only way to get an up-to-date copy is to delete the functions dir and build again). I'm assuming this behavior is also by design, so that the user can maintain their functions without Eleventy overwriting them, but again, maybe there needs to be more clarity on what to configure and where?

I'm happy to submit PRs and/or help clarify this area of the docs further once I understand it better, but I wanted to raise an issue first, just to make sure I'm not completely missing something here. Can also move over to a discussion too if this is more of an education thing.

[noelforte]

As a follow-up, the solution provided in Discussion #2137 appears to be the way to do it, but as mentioned above the documentation doesn't make clear that config: is something that needs to be added manually to the serverless function post-bundle, since adding config to the bundler configuration doesn't appear to have any effect.

[noelforte]

Follow-up-to-the-follow-up: with the deprecation, removal, and phasing out of the vendor-specific plugins like Serverless and Edge, I'm hoping there will be more guidance as we get closer to v3.0.0 on running Eleventy server-side. Specifically, my use case is that my site is 99.9% static, but there's always the case of one or two pages that I want to be able to password-protect. Then I can serve page content to "authenticated" users and fallback content to everyone else.

I tried running Eleventy in a Netlify Edge Function but ran into issues. Hoping this is something that can be documented on soon!

[zachleat]

Stale per project slipstream changes in #3074. Please group up at #3129 for further instructions!