netlify-functions - freeCodeCamp.org

How to Hide API Keys in Frontend Apps using Netlify Functions

Franklin Ohaegbulam — Tue, 07 Feb 2023 23:46:43 +0000

Netlify is a popular web development platform that makes it easier to build, deploy, and manage websites.

You can use Netlify to host websites, and it helps you update and release new changes. It also provides additional features such as security, user authentication and authorization services, and more.

This guide focuses on showing you how to set up a Netlify serverless function to hide Application Programming Interface (API) keys in a client-side application.

For this lesson, you will create a stock photo search engine web application, deploy it on Netlify, and make an API call to the Pixabay API using Netlify serverless functions.

This is the same process for front-end applications built with ReactJS, NextJS, VueJS, Angular, or other JavaScript frameworks.

Prerequisites

To follow along with this tutorial, you should have the following:

Netlify account (you can sign up here)
Basic understanding of RESTful APIs, Lambda functions, and async/await concepts.

The final demo app lives in the main branch on GitHub: https://netlify-func-demo.netlify.app

What is a Netlify function?

Netlify functions are serverless or lambda functions provided by Netlify. You use them to deploy server-side code or backend logic without the need for a dedicated server.

The purpose of this Netlify function is to manage serverless event-driven code and send HTTP requests that return a JSON response.

"Serverless functions, branded as Netlify Functions when running on Netlify, are a way to deploy server-side code as API endpoints" - Netlify Docs

It securely accesses environment variables behind the scenes via the Amazon Web Services (AWS) lambda function.

Secret credentials such as access tokens or API keys, hidden solely using environment variables, are less secure. This is because they can be easily retrieved from the Developer Tools through the API fetch request in the browser.

The API keys, if hijacked, can be misused by malicious actors, which might affect your app build threshold or cost you more if it's a paid API service.

Other serverless functions used for running code without having to manage servers include AWS Lambda functions, Azure functions, and Google cloud functions.

How to Set Up a Client-side Application

How to Clone the Demo App

To get started with this tutorial, you can clone the stock photo search engine app GitHub repository. See the live preview on Netlify at https://netlify-func-demo.netlify.app.

The first step is to clone the repository:

git clone https://github.com/frankiefab100/netlify-serverless-functions-demo.git

Next, change to the netlify-serverless-functions-demo directory.

 cd netlify-serverless-functions-demo

Then you'll need to install dependencies.

npm install
#OR 
yarn add

Now run the development server. Run the following command to start the app on the server:

netlify dev

The app will be ready on https://localhost:8888.

Alternatively, you can skip the above steps if you wish to follow along by building the app from scratch. In the next step, you will build a stock photo search engine JavaScript application.

How to Build the Demo App using JavaScript

The first step is to set up a front-end app. Open your favorite code editor, such as VS Code.

Then, create a dist directory and inside it create an index.html file. Populate it with the following code:

html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" href="style.css" />
    <title>Stock Photos Search Enginetitle>
  head>
  <body>
    <div class="container">
      <header>
        <h1>Search For Stock Photosh1>
        <div class="search-section">
          <input
            type="text"
            name="search"
            class="search"
            placeholder="Enter a keyword"
          />
          <input
            id="searchBtn"
            class="search-btn"
            type="submit"
            value="Search"
          />
        div>
      header>

      <div class="photo-wrapper">
        <img src="" alt="" class="photo" />
      div>
    div>

    <script src="./script.js" type="module">script>
  body>
html>

In the same dist directory, add the following styling to style.css:

/* dist/style.css */
* {
  box-sizing: border-box;
  margin: 0;
  padding: 0;
}

body {
  color: #222;
  font-family: "Roboto", sans-serif;
  font-size: 1rem;
  margin: 0 auto;
  width: 100vw;
  height: 100vh;
}

.container {
  display: flex;
  flex-direction: column;
  justify-content: center;
  align-items: center;
  text-align: center;
  min-height: 100vh;
  min-width: 100vw;
  width: 100%;
  height: 100%;
}

h1 {
  padding-bottom: 20px;
}

.search-section {
  display: inline;
  text-align: center;
  min-width: 310px;
}

.search,
.search-btn {
  border: none;
  border-radius: 5px;
  font-size: 1rem;
  padding: 15px;
  height: 50px;
}

.search {
  background-color: #d1f3bf;
  color: #222;
  min-width: 225px;
}

.search-btn {
  background-color: #04ab04;
  color: #f6f6f6;
  cursor: pointer;
  margin-left: 5px;
  min-width: 80px;
  transition: all 0.3s ease-in-out;
}

.search-btn:hover {
  background-color: #2dc22d;
}

.photo-wrapper {
  display: flex;
  gap: 15px;
  margin: 30px;
}

.photo-wrapper img {
  width: 200px;
}

The first step to using the Pixabay API is to sign up for an account with your email.

Pixabay API key section

As shown in the image above, your API key can be found below the parameters section in the Pixabay API Docs website.

Create an environment variable

Environment variables (commonly known as "env") are combinations of key/value pairs that can affect the behavior and processes of an operating system or application.

Using environment variables is recommended to configure third-party services and their credentials during development.

Install dotenv

Once you complete the account creation on Pixabay, open your terminal and install dotenv as a package. This will enable your app to read environment variables saved in the .env file.

npm install dotenv
#OR
yarn add -D dotenv

In the next step, you will save the API key in a .env file.

Create the .env file

In the root directory of your app, create a .env file and store the API keys copied from your Pixabay Profile.

PIXABAY_API_KEY=123456-7890

Where PIXABAY_API_KEY=123456-7890 represents the API key value.

Note: Replace this key/value pair with the appropriate value.

Create a .gitignore file

To avoid committing sensitive files and values such as node_modules and secret keys to a public repository, create a .gitignore file in the same project root directory and add the following to it:

node_modules
.env
.netlify

The .netlify folder which contains compiled serverless functions together with other files listed will be excluded when the project is pushed to GitHub or any other version control system.

Create a get request function

Now, you should add the fetch request logic in the script.js. You will adjust the API logic later using Netlify functions.

/* dist/script.js */
const dotenv = require("dotenv").config();

const searchbar = document.querySelector(".search");
const submitBtn = document.querySelector(".search-btn");
const photoWrapper = document.querySelector(".photo-wrapper");

submitBtn.addEventListener("click", () => {
  getPhoto(searchbar.value);
  searchbar.value = "";
});

window.addEventListener("keydown", (e) => {
  if (e.keyCode === 13) {
    getPhoto(searchbar.value);
    searchbar.value = "";
  }
});

async function getPhoto(keyword) {
  const apiKey = PIXABAY_API_KEY;
  let apiURL = `https://pixabay.com/api/?key=${apiKey}&q=${keyword}&image_type=photo&safesearch=true&per_page=3`;

  try {
    const response = await fetch(apiURL, {
      method: "GET",
      headers: { accept: "application/json" },
    });
    const data = await response.json();

    let imageURL = data.hits;

    imageURL.forEach((result) => {
      let imageElement = document.createElement("img");
      imageElement.setAttribute("src", `${result.webformatURL}`);
      photoWrapper.appendChild(imageElement);
    });
  } catch (error) {
    alert(error);
  }
}

Note: As mentioned earlier, if the codebase of this app is published on GitHub. The API key will still be accessible from the client side on a browser, although the .env file that contains the secret key was excluded.

To illustrate this, select the testing branch of this app repository. The Live site preview will display the following Reference Errors in your browser console:

Uncaught ReferenceError: require is not defined
Uncaught ReferenceError: require is not defined at getPhotos
Uncaught ReferenceError: process is not defined at getPhotos

This is because there is no way to reference the environment variables specified in the .env file, since they weren't committed to the public repository on GitHub.

In the next step, select and clone the [testing](https://github.com/frankiefab100/netlify-serverless-functions-demo/tree/testing) branch on your local machine with the following commands:

git clone https://github.com/frankiefab100/netlify-serverless-functions-demo.git
cd netlify-serveless-functions-demo
npm install
netlify dev

The app should launch on your browser via localhost:8888.

Now, go to the Developer tools, right-click and select Inspect. Alternatively, press the F12 key. Then, navigate to Network tab and tab on the getPhotos.js request URL.

API key displayed in the Network tab in Developer tools

You should see the API key publicly exposed in the Network tab's Headers section and return as a response data in your browser.

This is a security issue since the Network tab in the Developer tools is typically responsible to display informations such as the request URL, response status, and response data.

API key returned as a response data and exposed in the URL of the request

In the next section, you will find a way to secure the API key using Netlify functions.

How to Get Started with Netlify Functions

First, you'll need to go into your terminal and install Netlify CLI and Lambda as Devdependencies. You can do that by running this command:

npm install -g netlify-cli netlify-lambda
#OR 
yarn add -D netlify-cli netlify-lambda --save-dev

Add custom build and development commands in package.json

These commands build and start the app in the server and also launch the app on your web browser. Here's an example of how you might add these script commands in the package.json file:

"scripts": {
   "build": "npm run-script",
   "dev": "netlify dev"
 }

Install Axios

You will use the axios.get method, because it is a node function unlike the fetch method that is intended for browser runtime.

To install Axios, open your terminal and enter the command:

npm install axios
#OR
yarn add -D axios

In this case, you are working with a vanilla JavaScript app, so you should import Axios in the getPhotos.js file as:

const axios = require("axios");

For JavaScript libraries, like React, import it as follows:

import axios from "axios";

Create a serverless function

In the root of the project, create a folder named netlify,and inside it create another folder functions. In this functions directory, create a file named getPhotos.js.

You will create a serverless function in the getPhotos. This will completely hide the API keys while fetching images from the Pixabay API.

//netlify/functions/getPhotos.js 
require("dotenv").config();

const axios = require("axios");

exports.handler = async (event, context) => {
  try {
    const { keyword } = event.queryStringParameters;
    let response = await axios.get(
      `https://pixabay.com/api/?key=${process.env.PIXABAY_API_KEY}&q=${keyword}&image_type=photo&safesearch=true&per_page=3`,
      {
        headers: { Accept: "application/json", "Accept-Encoding": "identity" },
        params: { trophies: true },
      }
    );

    let imageURL = response.data.hits;

    return {
      statusCode: 200,
      body: JSON.stringify({ imageURL }),
    };
  } catch (error) {
    return {
      statusCode: 500,
      body: JSON.stringify({ error }),
    };
  }
};

Here, the process.env.PIXABAY_API_KEY references API key environment configuration specified in the .env file for development mode.

The keyword parameter accepts a string accessible in the queryStringParameters property and returns a response data stored in the variable imageURL. This will get passed to the script.js as request response (we'll discuss this later).

If the GET request is successful, it returns a response of statusCode 200 with the corresponding response as a JSON object. For errors, we will get an alert with the error message and status code.

Due to changes in version, Axios might return Buffer as a response in your terminal window, that looks like this:

Buffer response from Axios in Terminal

To prevent this, you should attach the following to the GET request:

 let response = await axios.get(
      `https://pixabay.com/api/?key=${process.env.PIXABAY_API_KEY}&q=${keyword}&image_type=photo&safesearch=true&per_page=3`,
      {
        headers: { Accept: "application/json", "Accept-Encoding": "identity" },
        params: { trophies: true },
      }
    );

Create a Netlify configuration file

In the project root directory, create a netlify.toml file. This file specifies how Netlify builds and deploys your app.

Now, add the following build configurations in netlify.toml:

[build]
  command = "npm run build"
  functions = "netlify/functions"
  publish = "dist"

Note:

command = "npm run build" triggers the Netlify CLI to build the app from the functions.
functions = "netlify/functions" indicates that the getPhotos functions exist in the netlify/functions directory.
publish = "dist" identifies dist as the directory where the file will be served from.

Update the script.js file with the Netlify functions request URL

Next, update the apiURL from this:

let apiURL = `https://pixabay.com/api/?key=${apiKey}&q=${keyword}&image_type=photo&safesearch=true&per_page=3`;

to the functions HTTP request endpoint:

  let apiURL = `/.netlify/functions/getPhotos?keyword=${keyword}`;

This serverless function will get queried to the client-side of your app through the endpoint: /.netlify/functions/getPhotos. Once a fetch request is sent, the getphotos function will be invoked and accessed in the script.js.

The getPhotos Netlify functions' response imageURL will be passed and the data accessed as the value of the keyword parameter in the query string of function. It will get loop through to return three images from the Pixabay API to the client-side.

The script.js file should look like this:

/* dist/script.js */
const searchbar = document.querySelector(".search");
const submitBtn = document.querySelector(".search-btn");
const photoWrapper = document.querySelector(".photo-wrapper");

submitBtn.addEventListener("click", () => {
  getPhoto(searchbar.value);
  searchbar.value = "";
  photoWrapper.innerHTML = "";
});

window.addEventListener("keydown", (e) => {
  if (e.keyCode === 13) {
    getPhoto(searchbar.value);
    searchbar.value = "";
    photoWrapper.innerHTML = "";
  }
});

async function getPhoto(keyword) {
  let apiURL = `/.netlify/functions/getPhotos?keyword=${keyword}`;

  try {
    const response = await fetch(apiURL, {
      method: "GET",
      headers: { accept: "application/json" },
    });
    const data = await response.json();

    for (let i = 0; i < data.imageURL.length; i++) {
      let imageElement = document.createElement("img");
      imageElement.setAttribute("src", `${data.imageURL[i].webformatURL}`);
      photoWrapper.appendChild(imageElement);
    }
  } catch (error) {
    alert(error);
  }
}

Note: From the codebase above, your environment variable is secure since it is accessed from the serverless function.

Run the development server

Now, execute your app by running the command:

netlify dev

This will load the getPhotos function via https://localhost:8888/.netlify/functions/getPhotos.

netlify build terminal output

Then, start the development server and launch the application in your default web browser on localhost:8888.

netlify function ready on https://localhost:8888

At this point, the Netlify function is fully setup, and you can now proceed to make GET HTTP requests.

How to Send Fetch Requests

Now that you already have the web app served, go ahead and send a fetch request. Enter some text in the search input field and hit Enter or click the button to fetch images from the Pixabay API.

flower images fetched from Pixabay API

For more information about the Pixabay API, see the Pixabay documentation.

The preceding command will send a request to the serverless function and then return six responses. Here's what the response looks like in your terminal windows:

Request from ::1: GET /.netlify/functions/getPhotos?keyword=flower
Response with status 200 in 4895 ms.

You can also use Developer tools through the Network tab to validate the request.

serverless function API response data

The fetch request returns our app URL, the getPhotos Netlify function, script.js and the images from Pixabay.

Netlify function fetch response from Network tab's header section in the browser

How to Host the App on the Remote Repository

Now, you should push your project to GitHub version control.

git add .
git commit -m"initial commit"
git push origin -u main

How to Deploy the App and Serverless Function on Netlify

Once you have published the project on GitHub, log in to Netlify and connect your GitHub account by granting authorization.

Import project for deployment on Netlify

As shown in the image above, click the Add A New Project and then search for the app repository from the list. Next, click on Build Your Site. This will take a few minutes to complete.

You just deployed the app from the Netlify UI. Your app is now ready at: https://netlify-func-demo.netlify.app..

The fetch request URL should look like this: https://netlify-func-demo.netlify.app/.netlify/functions/getPhotos.

Optional - How to Configure the Netlify App from the Dashboard

Alternatively, you can configure the Netlify command from the Netlify Dashboard. If these settings are already specified in netlify.toml, it will override any corresponding configuration.

First, select the project directory's Site settings.

Site settings for project directory on Netlify

Set the Build command and Publish directory

Navigate to Site settings > Deploy > Build & deploy and edit the following commands and then save the changes:

Build command: npm run build
Publish directory: dist

Build and deploy section on Netlify

Set the Functions directory

By default, Netlify uses netlify/functions as the directory to find the functions to deploy them. In our case, our serverless function getPhotos can be found in the netlify/functions directory.

Now we'll set a custom functions directory so Netlify can find your compiled functions. Go to Site settings > Functions and enter the directory path where the functions are stored in your repository.

Functions directory section on Netlify

How to Set Environment Variables for Production

In the Netlify Dashboard, click on Site settings > Build & deploy > Environment > Environment variables and then configure KEY/VALUE pairs as follows:

PIXABAY_API_KEY=your-api-key-here

Environment variables section on Netlify

Click on Save, and then redeploy your app so the changes can be added.

To redeploy the app on Netlify, navigate to Deploys > Trigger deploy. Next, select Clear cache and redeploy site.

Trigger redeployment tab on Netlify

Note: The environment variable (PIXABAY_API_KEY) name should match the one mentioned in the getPhotos codebase.

For a React application, prepend the API environment variable with the prefix REACT_APP so they can be read from the .env file.

 REACT_APP_PIXABAY_API_KEY=your-api-key-here

How to Initialize the Serverless Function to the Remote App

To connect your project directory to the existing web app deployed on Netlify, login to your Netlify account from the terminal:

netlify login

Next, initialize the app on Netlify by running the command in your terminal:

netlify init

Your app is now configured for continuous deployment via Netlify.

How to Build the Netlify Serverless Function

You need to link your app to site ID on Netlify before running the build command on your terminal. To connect your local project folder to its site ID on Netlify, enter the command in your terminal:

netlify link

This will prompt you to link the folder to a site through any of the following options:

Search by full or partial site name
Choose from a list of your recently updated sites
Enter a site ID

Once you select your preferred option, it will connect the project folder to the hosted site on Netlify. This allows you run Netlify CLI commands and also automatically deploy the project repository once there are any changes in the codebase.

In the next step, you will build a serverless function while it is running on the server. To activate the build command defined in netlify.toml file, run the following command:

netlify build

This runs the npm run-script command under the hood as specified in the package.json. Now, your serverless function in netlify/functions directory is packaged and bundled successfully!

How to Test the Application

To test and confirm that the Netlify function is working fine, run this command on your terminal:

netlify functions:serve

This injects your project environment variables from the .env file and runs the serverless function.

How to Confirm API Keys Security

To inspect your app and confirm that the API keys are hidden from the public, follow the steps below:

Click on your hosted app URL, and navigate to Developer tools by pressing the F12 key or right-clicking and selecting Inspect. Navigate to Network tab, where you should see the fetched data from the Pixabay API.

API key hidden from the public and unauthorized parties after inspection through the Developer tools

Now you've confirmed that you've successfully configured a serverless function and have it deployed on Netlify.

Conclusion

This tutorial introduced serverless functions, asynchronous JavaScript, and Restful API concepts.

Hopefully you now know how to create a serverless/lambda function and secure any sensitive value such as API keys in your frontend JavaScript application.

If you got stuck with anything, you can access the complete source code in this GitHub repository.

Thank you for reading! If you have any questions, feel free to reach out to me via Twitter.

Relevant Links

How I got Netlify Functions, Firebase, and GraphQL to work together at last

freeCodeCamp — Mon, 11 Nov 2019 13:00:00 +0000

By Jeff M Lowery

In a previous post I confessed defeat in attempting to get an AWS Lambda GraphQL server to connect to a Firebase server. I didn’t give up right away, though, and a short time later found a different Node package to achieve what I couldn’t before.

Why use AWS Lambda to host a GraphQL server? Scalability would be the obvious reason, but I did it to learn.

And I learned a lot

Especially when it came to deployment. I used Netlify Functions to manage the deployment of both the AWS Lambda functions and the React client that calls them. There was more to this than I originally thought.

There are several ways to deploy a project using Netlify:

zip-it-and-ship-it

This is a utility that works a lot like webpack: for each function, it creates an archive file which bundles the function along with its dependencies. Like webpack, it only pulls in dependencies that are actually required by the function.

Netlify expects /functions folder by convention. When writing new functions, its source is at the same level as any NodeJS modules it needs as dependencies. If you add a new function that has new module dependencies, then they go into the node_modules folder (using yarn add or npminstall --save).

The following shows two lambda functions along with a single node_modules folder:

To use zip-it-and-ship-it, you write a simple JavaScript program that is called by the package.json build script.

zipIt.js

const { zipFunctions } = require('@netlify/zip-it-and-ship-it')zipFunctions('functions', 'functions-dist')

And this would be invoked something like so:

package.json

"build": "npm-run-all build:*","build:app": "react-scripts build","build:functions": "node ./zipFuncs.js",

Once built, several .zip files are generated . Those archives contain the function code as well as a node_modules folder which is not the original, but contains only those dependencies needed by each function:

netlify-lambda

This deployment mechanism is similar to the above, but uses babel and webpack to perform its duties. If your comfortable and familiar with webpack, this might be the deployment option for you.

continuous deployment

The continuous deployment option is available if you’re using one of the supported repositories (GitHub, GitLab, or Bitbucket). Once you push changes to your repository, Netlify is notified and will run your build processes, which may involve zip-it-and-ship-it or netlify-lambda…but you also have the option of deploying unbundled functions to your repository, and Netlify will use zip-it-and-ship-it behind the scenes.

Netlify CLI

The Netlify CLI offers yet another way to deploy, without much fuss or mystery. There are two main deployment options:

netlify deploy will push the local project to a Netlify server. You first have to invoke the build step locally, though.
netlify dev creates a local server, along with a proxy to your lambda functions, and kicks off the application. It does not require a build step.

There is also a script to help you create your lambda functions: netlify function:create. If you use this method, you will get a folder structure different than shown previously:

In this case, each function has its own folder, along with a node_modules and package.json file (plus others not shown, such as .lock files). Similar to what would be in the .zip archives that zip-it-and-ship-it creates.

Now, if you do generate your lambdas this way, continuous deployment will break, as zip-it-and-ship-it doesn’t handle this folder structure by itself. You can put something like this in your build script to fix continuous deployment:

"build": "npm-run-all build:*",
"build:app": "react-scripts build",
"build:functions": "yarn --cwd functions/func1 install",
"build:functions": "yarn --cwd functions/func2 install",

These build steps will install the dependencies needed by each lambda.

The Example

Your homework assignment is to set up a Netlify account and a Firebase account. The app will use Netlify Identity to login to the Netlify service. You will also need to grab a Firebase credentials JSON file and put it somewhere in your project (the example uses fake-creds.json, which is FAKE, so won’t work).

About the application

Being a geek, I’m building a database of chess openings. I have an openings book in a JSON file, from which I’ll load the database. In this somewhat contrived example, the book is actually stored with the lambda function in the /functions/pgnfen folder (netlify function:create pgnfen), however the loading is triggered by the React client through a GraphQL mutation call.

Creating the lambda function

I used apollo-server-lambda add a GraphQL API frontend to the Firestore database. To talk to Firestore, I use firebase-admin. When using netlify function:create to create your function, it will ask what template to use; in this case, the correct choice is in blue:

In addition, I have added some utility functions and supporting GraphQL schema and resolvers.

The lambda function

The core of the whole operation is in /functions/pgnfen.js. It creates the server, logs into firebase, makes the necessary GraphQL declarations, and finally invokes the handler function that receives requests from the client and passes them on to the database via GraphQL resolvers:

/* eslint-disable no-unused-vars */
const apolloLambda = require('apollo-server-lambda');
const admin = require('firebase-admin');
const typeDefs = require('./schema.gql');
const { fetchGames, addOpenings } = require('./resolvers');

const {
  ApolloServer,
} = apolloLambda;

const credential = require('./fake-creds.json');


admin.initializeApp({
  credential: admin.credential.cert(credential),
});


const resolvers = {
  Query: {
    allGames: (root, args, context) => [], //TBD
  },
  Mutation: {
    addOpenings: async (root, args, context) => addOpenings(root, args, { ...context, admin }),
  },
};

const server = new ApolloServer({
  typeDefs,
  resolvers,
});

exports.handler = server.createHandler(
  {
    cors: {
      origin: '*',
      credentials: true,
    },
  },
);

The Schema

The schema defines the GraphQL API. ‘Nuf said.

const typeDefs = `

type Mutation {
  addOpenings(start: Int!, end: Int!) : Int! 
}
`

module.exports = typeDefs;

The resolver

This resolves the GraphQL addOpenings mutation into Firestore queries (batched, in this case), then sends back a count of documents submitted (if successful):

const openings = require('./scid.js');


const addOpenings = async (_, { start, end }, { admin }) => {
  const db = admin.firestore();
  const batch = db.batch();
  const fens = db.collection('chess/openings/fen');
  const data = openings.slice(start, end);

  data.forEach((opening) => {
    const id = opening.fen.replace(/\//g, '$');
    const doc = fens.doc(id);
    batch.set(doc, opening);
  });

  await batch.commit();

  return data.length;
};

module.exports = {  addOpenings };

The opening book

The JSON version of the opening book consists of an SCID (an opening identifier based on ECO), as well as the opening name and its FEN. Each one becomes a document in the database.

/* eslint-disable comma-dangle */
module.exports = [
  {
    SCID: 'A00b',
    desc: '"Barnes Opening"',
    fen: 'rnbqkbnr/pppppppp/8/8/8/5P2/PPPPP1PP/RNBQKBNR b KQkq - 0 1'
  },
  {
    SCID: 'A00b',
    desc: '"Fried fox"',
    fen: 'rnbqkbnr/pppp1ppp/8/4p3/8/5P2/PPPPPKPP/RNBQ1BNR b kq - 1 2'
  },
  {
    SCID: 'A00c',
    desc: '"Kadas Opening"',
    fen: 'rnbqkbnr/pppppppp/8/8/7P/8/PPPPPPP1/RNBQKBNR b KQkq h3 0 1'
  },
  ...
];

Creating the client

I’m using apollo-client in the React application. The easiest way to do so is create-react-app, then toss in [apollo-boost] to get a skeletal client up and running quickly. Then create a React component to trigger a call to the lambda, using the GraphQL API it provides.

The component will provide the start/end indices of the opening book to load, and a submit button.

Here’s a condensed version of the component code:

/* eslint-disable no-alert */
import React, { useState } from 'react';
import fetch from 'node-fetch';
import ApolloClient, { gql } from 'apollo-boost';

const styles = {
//...
};

const client = new ApolloClient({
  uri: '/.netlify/functions/pgnfen',  //the lambda URL
  fetch,
});

export default () => {
  const [start, setStart] = useState(0);
  const [end, setEnd] = useState(5);

  const clickHandler = async () => {
    const mutation = gql`mutation {
      addOpenings(start: ${start}, end: ${end})
    }`;

    // eslint-disable-next-line no-console
    const count = await client.mutate({ mutation })
      .catch((e) => { window.alert(e); });
    // console.dir(count);
    window.alert(`${count.data.addOpenings} documents written`);
  };

  const startEndHandler = (evt) => {
    if (evt.target.name === 'start') {
      setStart(evt.target.value);
    } else {
      setEnd(evt.target.value);
    }
  };

  return (
//...
      Row start:  
    
Row end:  
     
//...
  );
};

And the mutation response will show in a window alert box:

Added bonus!

Since I used apollo-server-lambda as a basis for the Netlify Function, I can go directly to the service endpoint via URL and it will bring up GraphQL Playground:

Here I can test queries and mutations prior to embedding them in my React client code.

Also, invoking netlify dev gives me a hot server courtesy of create-react-app, so I can see result of code changes in “real” time.

That’s it! Here’s a link to source.

How to work with FaunaDB + GraphQL

freeCodeCamp — Mon, 30 Sep 2019 17:01:00 +0000

By Jeff M Lowery

I have one or two projects I maintain on Netlify, in addition to hosting my blog there. It’s an easy platform to deploy to, and has features for content management (CMS) and lambda functions (by way of AWS).

What I needed for my latest project, though, was a database. Netlify has integrated FaunaDB: a NoSQL, document-oriented database. Fauna has recently boasted support for GraphQL, which is a big plus. At no charge and with a simplified setup, why not try it?

The database

Fauna has a unique approach to managing transactions across globally distributed data stores, so that that database records don’t get out of sync when they’re updated from points far and wide. This is a problem for global enterprises with high transaction volumes, but irrelevant for my small project.

The application

I’m a chess player of middling ability and I want to set up data to do analysis of master-level chess games. SQL or NoSQL didn’t matter—I’ve worked with both and either would support my application’s modest needs.

I love GraphQL, and have been using it since 2016. I don’t want my GraphQL schema exposed on the client side, though. The way around this is to have lambda functions to do the GraphQL requests, then have the client use those functions as a sort of proxy.

The implementation

I started with netlify-fauna-example. This doesn’t use GraphQL; instead the example’s Netlify Functions use FQL: Fauna Query Language. You can execute queries via fauna shell, or by using a NodeJS client module. The following uses the client to insert a todoItem into the *todos collection:

todos-create.js

  ...
  /* construct the fauna query */
  return client.query(q.Create(q.Ref('classes/todos'), todoItem))
    .then((response) => {
      console.log('success', response)
      /* Success! return the response with statusCode 200 */
      return callback(null, {
        statusCode: 200,
        body: JSON.stringify(response)
      })
    }).catch((error) => {
      console.log('error', error)
      /* Error! return the error with statusCode 400 */
      return callback(null, {
        statusCode: 400,
        body: JSON.stringify(error)
      })
    })

To use GraphQL, I need to create a database on Fauna, and then import a GraphQL schema. Once you’ve created an account on Fauna, you can do all this through their dashboard.

My new Fauna database

Once done, a set of collections (akin to tables in SQL) are created based on my imported GraphQL type definitions. Interestingly, new types and fields are also added to handle stuff like identifying instances and managing relations between types. For instance, my type for Opening was:

type Opening {
  desc: String!
  fen: String!
  SCID: String!
}

and when I go to the dashboard, open GraphQL Playground, and look at the schema, I see:

OpeningInput and OpeningPage were added by Fauna, in addition to the _id and _ts fields in Opening.

Queries and Mutations

There are certain queries and mutations that will be automatically implemented for you by Fauna if you define them in the schema you created. When I define the type to hold chess opening information, I may then include the following Query and Mutation definitions in my schema:

type Query {
 allOpenings: [Opening]
}

And FaunaDB will provide an implementation.

lambda functions

The original lambdas in netlify-fauna-example speak FQL. To convert these to GraphQL requests, use a fetch library such as node-fetch, and make HTTPS requests to the Fauna GraphQL endpoint using an client like the one included with apollo-boost:

import ApolloClient from 'apollo-boost';
import gql from 'graphql-tag'
import fetch from 'node-fetch'
import authorization from './authorization'

const URL = 'https://graphql.fauna.com/graphql'

const client = new ApolloClient({
  uri: URL,
  fetch,
  request: operation => {
    operation.setContext({
      headers: {
        authorization
      },
    });
  },
})


exports.handler = (event, context, callback) => {
  const allOpeningFens = gql`    
  query openings {
      allOpenings {
        data {fen}
      }
    }
  `;


  client.query({ query: allOpeningFens })
    .then(results => {
      callback(null, {
        statusCode: 200,
        body: JSON.stringify(results),
      })
    })
    .catch(e => callback(e))
}

The code above requests the FEN strings for all the openings in the Opening collection.

Are we done now? No.

_Photo by [Unsplash](https://unsplash.com/@sarti46?utm_source=ghost&utm_medium=referral&utm_campaign=api-credit">Massimo Sartirana / @resolver directive that can be used on mutation definitions. It will direct Fauna to use a user-defined function written in FQL; these can be written directly in the shell. For a collection of simple types like Opening, the resolver FQL is pretty straightforward.

First, I go to the FaunaDB Console Shell, and create the function add_openings:

CreateFunction({
  name: "add_openings",
  body: Query(
    Lambda(
      ["openings"],
      Map(
        Var("openings"),
        Lambda("X", Create(Collection("Opening"), { data: Var("X") }))
      )
    )
  )

Openings is an array, and the Map method executes Create call on each element. I then add a @resolver directive to my mutation definition in the schema I will import (referred to as a custom resolver):

type Mutation {
   addOpenings(openings: [OpeningInput]) : [Opening]! @resolver(name: "add_openings" paginated:false)
}

Now when the mutation is executed via the GraphQL client, add_openings is called and will insert all games passed in as a parameter to the mutation. From the GraphQL client it looks like this:

import ApolloClient from 'apollo-boost';
import gql from 'graphql-tag'
import fetch from 'node-fetch'
import authorization from './authorization'

const URL = 'https://graphql.fauna.com/graphql'

const client = new ApolloClient({
  uri: URL,
  fetch,
  request: operation => {
    operation.setContext({
      headers: {
        authorization
      },
    });
  },
})


exports.handler = (event, context, callback) => {

  const addScidDocs = gql`
  mutation($scid: [OpeningInput]) {
    addOpenings(openings: $scid) {desc}
  }
  `

  const json = JSON.parse(event.body)

  client.mutate({
    mutation: addScidDocs,
    variables: { scid: json },
  })
    .then(results => {
      console.log({ results })
      callback(null, {
        statusCode: 200,
        body: JSON.stringify(results),
      })
    })
    .catch(e => callback(e.toString()))

  // callback(null, { statusCode: 200, body: event.body })
}

The old chicken and egg problem

_Photo by [Unsplash](https://unsplash.com/@chromatograph?utm_source=ghost&utm_medium=referral&utm_campaign=api-credit">Chromatograph / @relation directive. That directive generates types used to relate two other type instances.

Here’s the relation in my import schema. Note the directive:

type Game {
  header: Header! @relation
  fens: [String!]!
  opening: Opening @relation
}

type Header {
    Event: String
    Date: String!
    White: String!
    WhiteElo: String
    Black: String!
    BlackElo: String
    ECO: String
    Result: String
}

To store a Game, I need to have also a required Header (Opening is not required). The relation is maintained by a Fauna-generated ref field on the Header. It's defined for the mutation through the use of a GameHeaderRelation type that allows the creation of both Game and Header in a single mutation. Here are the relevant generated types:

input GameHeaderRelation {
  create: HeaderInput
  connect: ID
}

input GameInput {
  header: GameHeaderRelation
  fens: [String!]!
  opening: GameOpeningRelation
}

type Mutation {
  createGame(data: GameInput!): Game!
}

Now to add a game with the required header info, I can call the mutation like so, from within the Playground:

mutation CreateGameWithHeader {
    createGame(data: {
        fens: [],
        header: { 
           create: {
           date: "2004.10.16", 
           white: "Morozevich, Alexander", 
           ...} ) {
        _id
        fens
        header {
          data {
            date
            white
          }
        }
    }
}

Let' say I now want to create a mutation to batch upload multiple games. Unfortunately I don’t have access to the generated GameHeaderRelation type, or any of the other input types. My import schema won’t validate without those defined if I try to use them in my bulk mutation definition. Again, bulk mutations are a ticketed feature request, so they should be available soon. Yet this type of issue will arise regarding any custom resolver’s use of types.

I though for a minute that the solution would be to download the generate schema (from Playground), then modify it with my bulk mutations. However, I am overriding __the otherwise-generated types on import, which is not what I want to happen.

The workaround: write a custom resolver in FQL

As stated, I need to ensure that when I create a function for my addGames resolver to call, there has to be a Header created first for each game.

The GraphQL Schema resolver attribute calls the FQL add_games function:

addGames(games: [GameInput]) : [Game]! @resolver(name: "add_games", paginated: false)

And here’s the function definition for add_games:

CreateFunction({
  name: "add_games",
  body: Query(
    Lambda(
      ["games"],
      Map(
        Var("games"),
        Lambda("X", [
          Create(Collection("Game"), {
            data: Merge(Var("X"), {
              header: Select(
                ["ref"],
                Create(Collection("Header"), {
                  data: Select(["header"], Var("X"))
                })
              )
            })
          })
        ])
      )
    )
  )
}

I’m not an FQL expert (see acknowledgments), but this code is readable (from innermost outward):

creates a header instance
selects its generated reference field “ref”
merges that reference as field “header” into the a data object “X”
“X” represents one element of the input array parameter “games” (GameInput)

I should note that one of Fauna’s engineers stated that maintaining references by hand is “tricky”. It requires understanding of what is going on beneath the covers. The @embedded type of relation may be easier to implement in FQL if the relation is one-to-one, as in this case.

Where to go from here…

Fauna’s support team and Slack community forum members have been exceedingly helpful with questions and have even offered help with implementing FQL functions. They’re also forthcoming when onsite documentation is incomplete or wrong.

Performance wasn’t great: the bulk insert of a 1000 small documents executed in matters of seconds, which is slow. However I didn’t use pagination in my resolvers, and that may make a significant difference. It is also possible that the GraphQL features are in a slower debuggable configuration as Fauna ramps up the feature set.

To write custom resolvers, it is necessary to master FQL. Its LISPish syntax will appeal to some, but I find it verbose and “nesty”. For simple CRUD operations it is fine. You may not find yourself writing many custom resolvers, either.

I chose to try Fauna not for its strengths, but for convenience. I may come back to it in a few months and see how it has progressed.

Acknowledgements

I’d like to thank Summer Schrader, Chris Biscardi, and Leo Regnier for their patience and insight.

I guess my life isn’t interesting enough: when I clone a project like netlify-fauna-example, I will usually then run npm update outdated and npm audit fix. I can expect to encounter issues when I do this, but in practice I usually resolve them in an hour or two.

Not this time. I deleted node_modules, package-lock.json, and even did a forced clean of the cache before reinstalling everything. Didn’t work. I eventually switched over to yarn, deleted the above (but left the updated version info in package.json alone) and installed. After a few hiccups, success! Here are the dependency versions I would up with:

  "dependencies": {
    "apollo-boost": "^0.4.4",
    "chess.js": "^0.10.2",
    "encoding": "^0.1.12",
    "faunadb": "^2.8.0",
    "graphql": "^14.5.7",
    "graphql-tag": "^2.10.1",
    "node-fetch": "^2.6.0",
    "react": "^16.9.0",
    "react-dom": "^16.9.0",
    "react-scripts": "^3.1.1"
  },
  "devDependencies": {
    "http-proxy-middleware": "^0.20.0",
    "markdown-magic": "^1.0.0",
    "netlify-lambda": "^1.6.3",
    "npm-run-all": "^4.1.5"
  },

How to use Netlify Functions in Elm

Cedd Burge — Wed, 28 Aug 2019 07:37:39 +0000

This worked example creates a simple Netlify Function and integrates it with an Elm application.

Netlify functions provide a very convenient way of working with AWS Lambdas, and they have an impressive array of example use cases, such as sending emails, processing payments and logging.

This example reads secrets from environment variables (to avoid them being exposed in the browser), but it is mostly generic, and can be adapted for other use cases easily.

Step 1 - Prerequisites

Create a repository for the code, probably on GitHub
npm i -g elm
npm install -g netlify-cli
npm i -g create-elm-app

Step 2 - Create vanilla Elm app

create-elm-app elm-app-with-netlify-function
cd elm-app-with-netlify-function
elm-app start

This should start a development server and load the app in your browser.

You can look at this commit in the companion repository to check that everything is ok.

Step 2 - Deploy on Netlify

npm init (and fill in sensible values)
npm i create-elm-app --save-dev (this adds create-elm-app to package.json, which is used by netlify)
Push the code to GitHub

You can see the results of this at this commit in the companion repository

Log in / Sign up / register with Netlify
Create a new site on Netlify
Choose your repository
Set the "Build command" to elm-app build
Set the "Public directory" to build
Click on "Deploy Site"

Netlify will now deploy the site, installing the dependencies specified in package.json, then running elm-app build and then serving the dist directory.

From now on, Netlify will attempt to deploy the latest code every time you push to GitHub.

Step 3 - Link Netlify Dev

netlify login
netlify link and choose the “Use current git remote url” option
Add “./netlify” to .gitignore
Add a netlify.toml file (from this commit in the companion repository)
netlify dev

This should start a local development server and load the app in your browser, in a similar way to step 1.

Step 4 - Add a netlify function

Run netlify functions:create to create a new netlify function. Choose the “js-token-hider” template, and name it "call-api".

This will create a javascript file for the function, and a package.json for its dependencies in “functions/call-api”.

Replace functions/call-api/call-api.js with this one in the companion repository

Now if you run netlify dev, the function will be served as well as the app, albeit on different ports. You can view the function in the browser to check that it is working (probably at http://localhost:34567/call-api or http://localhost:34567/.netlify/functions/call-api)

Step 5 - Call the netlify function from Elm

Install depdencies

elm install elm/json
elm install elm/http
elm install krisajenkins/remotedata

Update Main.elm to call the function and display the results (from the companion repository).

Instruct create-elm-app to proxy api calls to the function, by adding elmapp.config.js, as shown in the companion repository.

At this point, thee application runs, and successfully calls the api, but there are no secrets / environment variables yet, so the UI shows an error.

Step 6 - Add the secrets

Go to the “Site Settings” - “Build & Deploy” - “Continuous Deployment” - “Environment Variables” section on the Netlify website for your application.

Add environment variables for API_TOKEN and API_URL

Now when you run ‘netlify dev’ the app should now load in the browser and call the locally hosted netlify function, which will return the API_TOKEN and API_URL environment variables that you set on Netlify.

The same should be true on the live deployment on Netlify. You may need to “Trigger Deploy” manually on Netlify, so that it uses the new environment variables.

You can see the deployment of the companion repository at https://netlify-functions-with-elm.netlify.com

Conclusion

Netlify / serverless functions are extremely useful for creating / connecting to the backend services that your front end needs. They are also very east to set up, as this artcile (hopefully!) shows.

Create-elm-app is a great tool for developing Elm applications, and its simple proxy feature works well when developing Netlify functions.

Netlify Dev is great for replicating the production Netlify setup when developing locally (in this case by automatically providing the environment variables).

netlify-functions - freeCodeCamp.org

How to Hide API Keys in Frontend Apps using Netlify Functions

Prerequisites

What is a Netlify function?

How to Set Up a Client-side Application

How to Clone the Demo App

How to Build the Demo App using JavaScript

Sign Up for a Free Account on Pixabay

Create an environment variable

Install dotenv

Create the .env file

Create a .gitignore file

Create a get request function

How to Get Started with Netlify Functions

Add custom build and development commands in package.json

Install Axios

Create a serverless function

Create a Netlify configuration file

Update the script.js file with the Netlify functions request URL

Run the development server

How to Send Fetch Requests

How to Host the App on the Remote Repository

How to Deploy the App and Serverless Function on Netlify

Optional - How to Configure the Netlify App from the Dashboard

Set the Build command and Publish directory

Set the Functions directory

How to Set Environment Variables for Production

How to Initialize the Serverless Function to the Remote App

How to Build the Netlify Serverless Function

How to Test the Application

How to Confirm API Keys Security

Conclusion

Relevant Links

How I got Netlify Functions, Firebase, and GraphQL to work together at last

And I learned a lot

zip-it-and-ship-it

netlify-lambda

continuous deployment

Netlify CLI

The Example

About the application

Creating the lambda function

The lambda function

The Schema

The resolver

The opening book

Creating the client

Added bonus!

How to work with FaunaDB + GraphQL

The database

The application

The implementation

Queries and Mutations

lambda functions

Are we done now? No.

The old chicken and egg problem

The workaround: write a custom resolver in FQL

Where to go from here…

How to use Netlify Functions in Elm

Step 1 - Prerequisites

Step 2 - Create vanilla Elm app

Step 2 - Deploy on Netlify

Step 3 - Link Netlify Dev

Step 4 - Add a netlify function

Step 5 - Call the netlify function from Elm

Step 6 - Add the secrets

Conclusion