function-utils README is misleading

[maxime-michel]

It's been two months since I last encountered this, so I don't remember all the details, sorry. But it's been in my TODO list since then and I believe it is helfpul I nevertheless report the following:

The following snippet in functions-utils README.md is misleading:

module.exports = {
  // Add a Netlify Functions file or directory to a build
  async onPostBuild({ utils }) {
    await utils.functions.add('./path/to/function')
  },
}

The problem that I remember running into was that onPostBuild was too late to add the function. Only when switching to onPreBuild did the scenario work. Could you please confirm if you actually meant to use this event in the README?

[maxime-michel]

While on the topic of using utils.functions.add(), I was also wondering if you could provide guidelines on how to pass a file to the method. My plugin's NPM package comes with a resource script that I would like to add as a function. But my plugin's files are not available to me from the Netlify workspace, which is about building another repository. The way I do it for now is that I have the plugin write the function file to the current working directory like that:

fs.writeFileSync('counter.js', 'const https = require("https");\n');
fs.appendFileSync('counter.js', '\n');

There for sure must be a better way?

[ehmicky]

Hi @maxime-michel,

Yes, that's a typo, thanks for spotting it! Fixed in #1703.

For your problem, I am not sure I quite understand it. Would it be possible to rephrase it?

To make it clear: the only thing utils.functions.add(filePath) does is copying the file to the functions directory. Netlify Functions bundling then take care of the rest (but that's separate from both this utility and Build plugins in general).

[maxime-michel]

Cool, glad that was helpful despite the lack of details.

Sorry my workflow description isn't clear. I think I'm not understanding the scenario in which this API should be used. I'm happy it exists and able to use it nevertheless, don't get me wrong, but probably pushing it in an unexpected direction. Hence my request for more precisions in the README.

Anyway, let me try again:

1. a Netlify website is built, with my custom plugin kicking in during the build
2. my plugin uses utils.functions.add(filePath) in order to create a function automatically

Where can that file come from?

1. if the file has been in the website repository to start with, what is the use of this API? The website developer could have simply put it in functions himself. Or am I missing something?
2. if the file doesn't exist in the website repository yet, though, it means the API can be used to automatically setup a 3rd-party function for the website, which opens up a wide range of possibilities. But there, the only way I've found to generate the file, is with the terrible line-by-line creation.

[ehmicky]

Yes, the use case is probably 2.. It does not need to be line-by-line creation though. The only requirement is for the function to be available as its own file.

For example, maybe your plugin has a Function file that uses some templating language. The template is rendered based on the build, then the Function is added to the user's build.

[maxime-michel]

A template file, why didn't I think of that!

Good to hear I'm not misusing the API. Thanks a lot!