Gatsby Functions

[sidharthachatterjee]

Update (2021-06-09):

With Gatsby v3.7 (https://www.gatsbyjs.com/docs/reference/release-notes/v3.7) Gatsby Functions are available to everyone now. You can also use them on Gatsby Cloud now: https://www.gatsbyjs.com/blog/announcing-launch-of-functions-on-gatsby-cloud

---

We're introducing support for serverless functions in Gatsby and Gatsby Cloud. Learn more at the RFC at #27667

PR implemented in #30192

Full docs are at https://www.gatsbyjs.com/docs/how-to/functions/

How to use

Make sure your site has Gatsby v3.4 (or above) installed.

Add the FUNCTIONS flag to your gatsby-config.js:

module.exports = {
  flags: {
    FUNCTIONS: true
  },
  plugins: [...]
}

Start your develop server.

Write your first function at src/api/hello-world.js

export default function helloWorldHandler (req, res) {
  res.json({ hello: `world` })
}

Run in your terminal curl http://localhost:8000/api/hello-world

Glory in your functionalness.

Gatsby Functions are fully supported on Gatsby Cloud. If you're interested in helping add support for functions for other hosts, leave a comment.

[andrezimpel]

Been running into an issue using Gatsby 3.4.0. I did not include the gatsby-plugin-functions in the project and there is no function in the project.

This is what I was running into:
ENOENT: no such file or directory, copyfile '/usr/src/app/www/.cache/functions/manifest.json' -> '/usr/src/app/www/public/_functions.json'

[KyleAMathews]

Sorry about that. @LekoArts fixed it in #31092 just upgrade gatsby-plugin-google-cloud and you'll be fine.

[rodneylab]

Hi I'm running into an issue with using a package in the function. Just the import of the package crashes gatsby-cli. Everything works fine when I comment out the import. I am using Gatsby 3.4.1, Gatsby CLI 3.4.1.

CLI error:

/XXX/gatsby-functions-fauna/node_modules/yoga-layout-prebuilt/yoga-layout/build/Release/nbind.js:53
        throw ex;
        ^

TypeError: Cannot read property 'warn' of undefined
    at forEach (/XXX/gatsby-functions-fauna/node_modules/gatsby/src/utils/webpack-error-utils.ts:156:43)
    at Array.forEach (<anonymous>)
    at reportWebpackWarnings (/XXX/gatsby-functions-fauna/node_modules/gatsby/src/utils/webpack-error-utils.ts:156:15)
    at Watching.callback [as handler] (/XXXgatsby-functions-fauna/node_modules/gatsby/src/internal-plugins/functions/gatsby-node.ts:223:25)
    at /XXX/gatsby-functions-fauna/node_modules/webpack/lib/Watching.js:204:9
    at Hook.eval [as callAsync] (eval at create (/XXX/gatsby-functions-fauna/node_modules/webpack/node_modules/tapable/lib/HookCodeFactory.js:33:10), <anonymous>:6:1)
    at Watching._done (/XXX/gatsby-functions-fauna/node_modules/webpack/lib/Watching.js:201:28)
    at /XXX/gatsby-functions-fauna/node_modules/webpack/lib/Watching.js:129:21
    at Compiler.emitRecords (/XXX/gatsby-functions-fauna/node_modules/webpack/lib/Compiler.js:862:39)
    at /XXX/gatsby-functions-fauna/node_modules/webpack/lib/Watching.js:107:22
    at /XXX/node_modules/webpack/lib/Compiler.js:844:14
    at Hook.eval [as callAsync] (eval at create (/XXX/gatsby-functions-fauna/node_modules/webpack/node_modules/tapable/lib/HookCodeFactory.js:33:10), <anonymous>:6:1)
    at /XXX/gatsby-functions-fauna/node_modules/webpack/lib/Compiler.js:841:27
    at /XXX/gatsby-functions-fauna/node_modules/neo-async/async.js:2818:7
    at done (/XXX/gatsby-functions-fauna/node_modules/neo-async/async.js:3522:9)
    at Hook.eval [as callAsync] (eval at create (/XXX/gatsby-functions-fauna/node_modules/webpack/node_modules/tapable/lib/HookCodeFactory.js:33:10), <anonymous>:6:1)

Here is my function:

import { AkismetClient } from 'akismet-api';
import axios from 'axios';
import faunadb from 'faunadb';

const createComment = async ({ name, parentCommentId, text, markedSpam, slug }) => {
  const result = (async () => {
    try {
      const q = faunadb.query;
      const client = new faunadb.Client({
        secret: process.env.GATSBY_FAUNA_SECRET,
        domain: 'db.fauna.com',
        scheme: 'https',
      });
      const response = await client.query(
        q.Create(q.Collection(process.env.GATSBY_FAUNA_COLLECTION), {
          data: {
            date: new Date().toISOString(),
            markedSpam: false,
            name,
            parentCommentId,
            slug,
            text,
          },
        }),
      );
      return { successful: true, message: response };
    } catch (error) {
      return { successful: false, message: error };
    }
  })();
  return result;
};

// const spamCheck = async ({
//   email, ip, name, text, userAgent,
// }) => {
//   const client = new AkismetClient({ key: AKISMET_API_KEY, blog: SITE_URL });
//   return client.checkSpam({
//     ip,
//     useragent: userAgent,
//     content: text,
//     email,
//     name,
//   });
// };

const triggerRebuild = async () => {
  if (!process.env.GATSBY_CLOUD_SITE_ID) {
    return { successful: false, message: 'Gatsby Cloud Site ID is not defined.' };
  }
  const result = (async () => {
    try {
      const response = await axios({
        url: `https://webhook.gatsbyjs.com/hooks/data_source/publish/${process.env.GATSBY_CLOUD_SITE_ID}`,
        method: 'POST',
      });
      return { successful: true, message: response };
    } catch (error) {
      let message;
      if (error.response) {
        message = `Server responded with non 2xx code: ${error.response.data}`;
      } else if (error.request) {
        message = `No response received: ${error.request}`;
      } else {
        message = `Error setting up response: ${error.message}`;
      }
      return { successful: false, message };
    }
  })();
  return result;
};

export default async function handler(req, res) {
  if (req.method !== 'POST') {
    res.status(405).send('Method not allowed');
  } else {
    const { email, name, parentCommentId, slug, text } = req.body;
    const ip = req.headers['client-ip'];
    const userAgent = req.headers['user-agent'];
    let markedSpam;
    let akismetError;

    // try {
    //   markedSpam = await spamCheck({
    //     email, ip, text, userAgent,
    //   });
    // } catch (error) {
    //   akismetError = error.message;
    // }

    // if (akismetError) {
    //   res.status(400).send(akismetError);
    // } else {
    const createCommentResult = await createComment({
      name,
      parentCommentId,
      text,
      markedSpam,
      slug,
    });
    if (!createCommentResult.successful) {
      res.status(400).send(createCommentResult.message);
    } else {
      await triggerRebuild();
      res.status(200).send('All is well that ends well.');
    }
  }
}

works fine if I comment out the first line where akismet-api is imported.

Full repo is here: https://github.com/rodneylab/gatsby-functions-fauna

Do I need to add some extra webpack config to use this package?

Thanks,
Rodney

[rodneylab]

Thanks for quick response Kyle. Will hang on for PR merge to try it out.

[KyleAMathews]

This is out now in 3.5. When you have it up and running, share a link, I'd love to see it in action!

[rodneylab]

Thanks Kyle, it's all working like clockwork now. Thanks for the quick fix.

The site is up at:

https://gatsbyfunctionsfaunamain.gatsbyjs.io/

this is demo blog so, please feel free to play around with it:

• Try going to a blog post and submitting a non-spammy comment. The site will automatically rebuild on Gatsby Cloud. Give it a couple of minutes and refresh, and your comment will be included with all the other site content statically generated on build.
• To test a spam comment, either set the name field to viagara-test-123 or email to akismet-guaranteed-spam@example.com and submit the comment. You will see the same message that your comment will be reviewed, but this time the site will not be rebuilt and even when it is later rebuilt (manually or by a genuine comment), the spam comment will not be included.

One request... could you make the client-ip header available in the handler request headers? Seems not to be exposed currently. This will be used in the Akismet spam detection. Using the client front end to get the user IP for now as a workaround.

Happy to include some Akismet and fauna simplified examples in your gatsby-functions-beta repo. Just let me know.

Rodney

[KyleAMathews]

soooo cool! Just tried it out on https://gatsbyfunctionsfaunamain.gatsbyjs.io/best-medium-format-camera-for-starting-out/ 🎉

Fauna + Akismet examples would be fantastic! Just put up a PR.

Yeah, getting the client ip set on the header would be great. I'll relay it to the team.

[KyleAMathews]

The team's aware of the issue. I created this roadmap item so you & others interested can follow along. Just pop over and upvote it & you'll get notified when it's shipped https://gatsby.canny.io/gatsby-cloud/p/set-x-forwarded-for-header-for-functions-to-get-the-actual-client-ip

[michaellopez]

I gave functions a quick try. I am basing most of my feedback on my long experience with Vercels offering, which I like very much. I'd very much like Gatsby Cloud to offer the same or something simliar to that experience regarding functions. I'd be happy to help provide more data, testing or feedback if needed.

The first thing I set out to try was the Typescript support. Typescript support did not work for Gatsby functions. But I managed to solve it. It took me a while to figure out that when following one of Gatsbys getting started articles I ended up using a Gatsby starter that didn't install version 3.5.0. That version is required for proper TS support. So once I updated that it worked smoothly.

The second thing I wanted to try was how the functions service handled headers. I am very keen on using cache-control headers properly to reduce function executions and accelerate our users experience. Proper cache header can make a huge difference in both regards. To my surprise functions in Gatsby currently don't support it on Gatsby Cloud. It works locally, I can control basically any header in the response locally. But on Gatsby Cloud the functions seem to be behind Varnish and no matter what I did I couldn't get it to respect my functions headers. Varnish seems to be configured to currently override the cache-control header to always be cache-control: public, max-age=0, must-revalidate. That basically forces the function to run every request to be able to calculate the 304 status code. So the user still has to wait for this calculation, but they do avoid the download of data if it is the same. Also the function executes again (for no reason) and starts chipping away at the invocation quota (for no reason). I don't mind having this approach as the default for developers that do not need to fine grained control of cache-control headers, those that just want to deploy a function and it "Just Works ™️ ", cache invalidation and all. But for us "power users" I would very much like it if Varnish or whatever you use in front of the functions would respect all headers that functions return/set.

The third thing is support for s-maxage and stale-while-revalidate. My initial testing seem to point to the fact that they are currently unsupported. Currently I see this:

< via: 1.1 varnish
< x-served-by: cache-bma1636-BMA
< x-cache: MISS
< x-cache-hits: 0

x-served-by is different for all requests and also that fact that the responses always show a fresh timestamp indicate that s-maxage isn't supported. I didn't do enough testing to check stale-while-revalidate due to this, so I'm just assuming that it is not supported either. It would make a big difference if these headers where supported by the CDN/thing in front of the functions.

That's it for now during my simple quick test.

I will continue to try function out and push them to their limits. I am very excited about this!

My test function:

// src/api/hello.ts
import { GatsbyFunctionRequest, GatsbyFunctionResponse } from "gatsby"
export default function handler(
  req: GatsbyFunctionRequest,
  res: GatsbyFunctionResponse
) {
  res.setHeader("Cache-Control", [
    "max-age=60",
    "s-maxage=60",
    "stale-while-revalidate=60",
  ])
  res.send(`I am TYPESCRIPT: ${new Date().toString()}`)
}

It is deployed at https://gswpgatsby.gatsbyjs.io/api/hello

[krismorf]

I have a question about functions.
Is it possible to run a graphql query inside the api/ folder, and then export the result in either GraphQL/REST?

[michaellopez]

@krismorf @KyleAMathews I gave it a shot here https://github.com/michaellopez/gatsby/tree/feat/function-queries. The commit basically adds the ability to do queries in the functions. E.g.

import { GatsbyFunctionRequest, GatsbyFunctionResponse, graphql } from "gatsby"

export default function handler(
  req: GatsbyFunctionRequest,
  res: GatsbyFunctionResponse
) {
  const data = graphql`
    query {
      site {
        id
        siteMetadata {
          title
        }
      }
    }
  `

  res.send(`Data: ${JSON.stringify(data)}`) //  Data: {"data":{"site":{"id":"Site","siteMetadata":{"title":"Gatsby Default Starter"}}}}
}

This should improve on @krismorf use case of exposing data.

I accomplished this by moving function compilation from onPreBootstrap to onPostBuild for build and onCreateDevServer for develop and adjusting query extraction to support functions.

I'm aware that Gatsby is reluctant to add more API surface so adding a new phase/step felt outside the scope when I started looking into this. So I tried to keep it minimal, but the commit does touch files outside packages/gatsby/src/internal-plugins/functions/, unfortunately. Mainly to add support for query extraction that is not page query or static query. I started out wanting to only do it from inside packages/gatsby/src/internal-plugins/functions/ (and I believe it might be possible, just have to think about and fiddle with it a bit more) but ended up doing it this way just to get something on here to move the discussion forward and showcase the approach in case its an acceptable path forward. Also no tests, so naturally consider it a draft/wip to give us some direction here. Any feedback appreciated.

[KyleAMathews]

Huh, super interesting!

This definitely works. The basic idea here is to bind data at build-time to a function. Accessing it through the data layer is an obvious step — I wonder a) how common this need is i.e. common enough to create a special API for it and b) if it'd be better to just make it generic. E.g. a function could export another function like getStaticData that'd be called at build-time e.g.

export async function getStaticData ({ graphql }) {
  const data = await graphql(graphql`
    query {
      site {
        id
        siteMetadata {
          title
        }
      }
    }
  `)

  return data
}

export default function handler (req, res, { data }) {
  res.json(data)
}

BTW on timing — we're approaching the initial GA launch of functions so it's very unlikely we'll make any changes discussed here (other than when we run functions) in the near term.

[michaellopez]

@KyleAMathews I also contemplated that exact pseudo code you wrote when writing my branch. I discarded it because it felt strange and awkward to alter the handler signature, it feels very "set in stone" as (req, res) almost everywhere. I'm not really knowledgeable as to how functions are deployed in Gatsby Cloud, but I would really like Gatsby Functions to remain compatible with/deployable on other services that offer cloud functions too. Anyway, that's why I opted for my approach.

Also, I'm not so sure that making it generic like that would have any great benefits, as the data fetching from any source but Gatsby graphql server could be done in the handler itself at runtime. Having said that maybe someone else will come up with a great use case/pattern with an approach like getStaticData.

Regarding timing, understood. I can make a PR with only the order functions are compiled in, if you want that?

[KyleAMathews]

We're planning to extract a functions runtime as a separate package that will consolidate how we run functions in gatsby develop, gatsby serve and in Cloud (we have to manually keep them in sync right now which isn't great). That could be used to setup Gatsby Functions on other services. So a third "context" parameter would be manageable.

That being said, yeah, there's not a lot of benefit to shipping support for fetching from elsewhere because as you say, you can easily do that at runtime.

Yeah, if you could PR moving function compilation to onPostBootstrap to unlock the write out json and import it into a function approach. Writing out the data in exports.createPages then would work (which doesn't make a lot of sense semantically). I'm on vacation now actually so won't review until next week.

[michaellopez]

@KyleAMathews OK, I'll see what I can do!

[chenxizhang]

How can I deploy functions into Azure instead of Gatsby cloud?

[KyleAMathews]

Functions need some glue code to be supported on different hosting platforms. E.g. Netlify recently added support https://www.netlify.com/blog/2021/06/03/how-to-enable-gatsby-functions-on-netlify/

Functions are compiled to .cache/functions so for Azure, you'd need to deploy those to Azure functions & setup routing.

[chenxizhang]

Thank you Kyle, sorry I have no idea on this, how to run this (.cache/functions likely is some static output) without a plugin like you mentioned above? Azure has a static web app template, which supports the Azure function by default. But I like the api function which gatsby provides directly.

It will be great if you can take a look on this. Thanks

https://docs.microsoft.com/en-us/azure/static-web-apps/add-api?tabs=vanilla-javascript

[KyleAMathews]

It's going to take someone with some familiarity with Azure to solve this. Could you reach out to Azure directly?

[LekoArts]

Hello everyone!

With Gatsby v3.7 (https://www.gatsbyjs.com/docs/reference/release-notes/v3.7) Gatsby Functions are available to everyone now. You can also use them on Gatsby Cloud now: https://www.gatsbyjs.com/blog/announcing-launch-of-functions-on-gatsby-cloud

If you have questions or feature requests regarding Gatsby Functions, please use GitHub discussions: https://github.com/gatsbyjs/gatsby/discussions

If you have found a bug, please report an issue: https://github.com/gatsbyjs/gatsby/issues/new?assignees=&labels=type%3A+bug&template=bug_report.md