npm

Netlify Lambda

This is an optional tool that helps with building or locally developing Netlify Functions with a simple webpack/babel build step. For function folders, there is also a small utility to install function folder dependencies.

The goal is to make it easy to write Lambda's with transpiled JS/TypeScript features and imported modules.

When to use Netlify Dev or netlify-lambda or both?

Installation

We recommend installing locally rather than globally:

npm install netlify-lambda

This will ensure your build scripts don't assume a global install which is better for your CI/CD (for example with Netlify's buildbot).

If you don't have a netlify.toml file, you'll need one (example). Define the functions field where the functions will be built to and served from, e.g.

# example netlify.toml
[build]
  command = "npm run build"
  functions = "lambda" #  netlify-lambda reads this
  publish = "build"

Usage

We expose three commands:

netlify-lambda build <folder>
netlify-lambda install [folder]
 
## legacy command - only preserved for backward compatibility 
netlify-lambda serve <folder> 

netlify-lambda install

Sometimes your function folders will have dependencies unique to them, managed by a package.json local to that folder. This is a small utility function for installing those dependencies either on your local machine or as part of your build commands.

By default it just runs on the functions folder specified in netlify.toml. Here's all you need to add to your package.json (see this example):

// package.json
{
   "dependencies": { // you probably don't want it in devDependencies! This is a common gotcha https://www.netlify.com/docs/build-gotchas/#devdependencies
       "netlify-lambda": "^1.6.0"
   },
   "scripts": {
       "postinstall": "netlify-lambda install"
   }
}

This is what you should do if you are just using Netlify Dev without netlify-lambda.

If you're using netlify-lambda serve or build, however, you will want to run this install on the source folder rather than the dist/netlify.toml functions folder, so you should run it with the same exact folder name as with those other commands:

netlify-lambda install <folderName>

We don't anticipate you will use this as often but it can be handy.

netlify-lambda build

At a high level, netlify-lambda takes a source folder (e.g. src/lambda, specified in your command) and outputs it to a built folder, (e.g. built-lambda, specified in your netlify.toml file).

The build function will run a single build of the functions in the folder.

The serve function will start a dev server for the source folder and route requests with a .netlify/functions/ prefix, with a default port of 9000:

folder/hello.js -> http://localhost:9000/.netlify/functions/hello

It also watches your files and restarts the dev server on change. Note: if you add a new file you should kill and restart the process to pick up the new file.

IMPORTANT:

• You need a netlify.toml file with a functions field.
• Every function needs to be a top-level js/ts/mjs file. You can have subfolders inside the netlify-lambda folder, but those are only for supporting files to be imported by your top level function. Files that end with .spec.* or .test.* will be ignored so you can colocate your tests.
• Function signatures follow the AWS event handler syntax but must be named handler. We use Node v8 so async functions are supported (beware common mistakes!). Read Netlify Functions docs for more info.
• Functions time out in 10 seconds by default although extensions can be requested. We try to replicate this locally.

// legacy callback style - not encouraged anymore, but you'll still see examples doing this
exports.handler = function(event, context, callback) {
// your server-side functionality
callback(null, {
  statusCode: 200,
  body: JSON.stringify({
    message: `Hello world ${Math.floor(Math.random() * 10)}`
  })
});
};

or you can use async/await:

// modern JS style - encouraged
export async function handler(event, context) {
  return {
    statusCode: 200,
    body: JSON.stringify({ message: `Hello world ${Math.floor(Math.random() * 10)}` })
  };
}

⚠️ The above example only works with netlify-lambda because it uses ES module syntax! If you get Function invocation failed: SyntaxError: Unexpected token 'export'. errors, this is why.

For more Functions examples, check:

• https://functions-playground.netlify.com/ (introductory)
• https://functions.netlify.com/examples/ (our firehose of all functions examples)
• the blogposts at the bottom of this README

netlify-lambda serve (legacy command)

This command is pretty much superceded by Netlify Dev. We only keep it around for legacy/backward compatibility support reasons.

netlify-lambda serve (legacy command): Using with create-react-app, Gatsby, and other development servers

netlify-lambda serve (legacy command): Proxying for local development

⚠️IMPORTANT! PLEASE READ THIS ESPECIALLY IF YOU HAVE CORS ISSUES⚠️

When your function is deployed on Netlify, it will be available at /.netlify/functions/function-name for any given deploy context. It is advantageous to proxy the netlify-lambda serve development server to the same path on your primary development server.

Say you are running webpack-serve on port 8080 and netlify-lambda serve on port 9000. Mounting localhost:9000 to /.netlify/functions/ on your webpack-serve server (localhost:8080/.netlify/functions/) will closely replicate what the final production environment will look like during development, and will allow you to assume the same function url path in development and in production.

• If you are using with create-react-app, see netlify/create-react-app-lambda for an example of how to do this with create-react-app. setupProxy is partially documented in the CRA docs. You can also learn how to do this from scratch in a video: https://www.youtube.com/watch?v=3ldSM98nCHI
• If you are using Gatsby, see their Advanced Proxying docs. This is implemented in the JAMstack Hackathon Starter.
• If you are using React-Static, check https://github.com/nozzle/react-static/issues/380.
• If you are using Nuxt.js, see this issue for how to proxy.
• If you are using Vue CLI, you may just use https://github.com/netlify/vue-cli-plugin-netlify-lambda/.
• If you are using with Angular CLI, see the instructions below.

Example webpack config:

module.exports = {
  mode: "development",
  devServer: {
    proxy: {
      "/.netlify": {
        target: "http://localhost:9000",
        pathRewrite: { "^/.netlify/functions": "" }
      }
    }
  }
};

this.http.get("/.netlify/functions/jokeTypescript");

{
  "/.netlify/functions/*": {
    "target": "http://localhost:9000",
    "secure": false,
    "logLevel": "debug",
    "changeOrigin": true
  }
}

  ng serve --proxy-config proxy.config.json

  "scripts": {
    "start": "ng serve --proxy-config proxy.config.json",
    "build": "ng build --prod --aot && yarn nlb",
    "nls": "netlify-lambda serve src_functions",
    "nlb": "netlify-lambda build src_functions"
  }

touch server.js
yarn add -D http-proxy-middleware express

// server.js
/* eslint-disable no-console */
const express = require("express");
const next = require("next");
 
const devProxy = {
  "/.netlify": {
    target: "http://localhost:9000",
    pathRewrite: { "^/.netlify/functions": "" }
  }
};
 
const port = parseInt(process.env.PORT, 10) || 3000;
const env = process.env.NODE_ENV;
const dev = env !== "production";
const app = next({
  dir: ".", // base directory where everything is, could move to src later
  dev
});
 
const handle = app.getRequestHandler();
 
let server;
app
  .prepare()
  .then(() => {
    server = express();
 
    // Set up the proxy.
    if (dev && devProxy) {
      const proxyMiddleware = require("http-proxy-middleware");
      Object.keys(devProxy).forEach(function(context) {
        server.use(proxyMiddleware(context, devProxy[context]));
      });
    }
 
    // Default catch-all handler to allow Next.js to handle all other routes
    server.all("*", (req, res) => handle(req, res));
 
    server.listen(port, err => {
      if (err) {
        throw err;
      }
      console.log(`> Ready on port ${port} [${env}]`);
    });
  })
  .catch(err => {
    console.log("An error occurred, unable to start the server");
    console.log(err);
  });

// package.json
  "scripts": {
    "start": "cross-env NODE_ENV=dev npm-run-all --parallel start:app start:server",
    "start:app": "PORT=3000 node server.js",
    "start:server": "netlify-lambda serve functions"
  },

Webpack Configuration

By default the webpack configuration uses babel-loader to load all js files. Any .babelrc in the directory netlify-lambda is run from will be respected. If no .babelrc is found, a few basic settings are used.

If you need to use additional webpack modules or loaders, you can specify an additional webpack config with the -c/--config option when running either serve or build.

For example, have a file with:

// webpack.functions.js
module.exports = {
  optimization: { minimize: false }
};

Then specify netlify-lambda serve --config ./webpack.functions.js. If using VSCode, it is likely that the sourceMapPathOverrides have to be adapted for breakpoints to work. Read here for more info on how to modify the webpack config.

If you're using firebase SDK and other native modules, check this issue and use this plugin:

//./config/webpack.functions.js
const nodeExternals = require('webpack-node-externals');

module.exports = {
  externals: [nodeExternals()],
};

The additional webpack config will be merged into the default config via webpack-merge's merge.smart method.

Babel configuration

The default webpack configuration uses babel-loader with a few basic settings.

However, if any .babelrc is found in the directory netlify-lambda is run from, or folders above it (useful for monorepos), it will be used instead of the default one.

It is possible to disable this behaviour by passing --babelrc false.

If you need to run different babel versions for your lambda and for your app, check this issue to override your webpack babel-loader.

Use with TypeScript

We added .ts and .mjs support recently - check here for the PR and usage tips.

1. Install @babel/preset-typescript

npm install --save-dev @babel/preset-typescript

You may also want to add typescript @types/node @types/aws-lambda.

1. Create a custom .babelrc file:

{
  "presets": [
    "@babel/preset-typescript",
    "@babel/preset-env"
  ],
  "plugins": [
    "@babel/plugin-proposal-class-properties",
    "@babel/plugin-transform-object-assign",
    "@babel/plugin-proposal-object-rest-spread"
  ]
}

1. (Optional) if you have @types/aws-lambda installed, your lambda functions can use the community typings for Handler, Context, Callback. See the typescript instructions in create-react-app-lambda for an example.

Check https://github.com/sw-yx/create-react-app-lambda-typescript for a CRA + Lambda full Typescript experience.

CLI flags/options

There are additional CLI options:

-h --help
-c --config
-p --port
-s --static
-t --timeout
-b --babelrc

--config option

If you need to use additional webpack modules or loaders, you can specify an additional webpack config with the -c/--config option when running either serve or build.

For example, have a file with:

// webpack.functions.js
module.exports = {
  optimization: { minimize: false }
};

Then specify netlify-lambda serve --config ./webpack.functions.js.

--timeout option

(This is for local dev/serving only) The default function timeout is 10 seconds. If you need to adjust this because you have requested extra timeout, pass a timeout number here. Thanks to @naipath for this feature.

--port option

The serving port can be changed with the -p/--port option.

--static option

If you need an escape hatch and are building your lambda in some way that is incompatible with our build process, you can skip the build with the -s or --static flag. More info here.

--babelrc

Defaults to true

Use a .babelrc found in the directory netlify-lambda is run from. This can be useful when you have conflicting babel-presets, more info here

Netlify Identity

Make sure to read the docs on how Netlify Functions and Netlify Identity work together. Basically you have to make your request with an authorization header and a Bearer token with your Netlify Identity JWT supplied. You can get this JWT from any of our Identity solutions from gotrue-js to netlify-identity-widget.

Since for practical purposes we cannot fully emulate Netlify Identity locally, we provide simple JWT decoding inside the context of your function. This will give you back the user info you need to work with.

Minor note: For the identity field, since we are not fully emulating Netlify Identity, we can't give you details on the Identity instance, so we give you unambiguous strings so you know not to rely on it locally: NETLIFY_LAMBDA_LOCALLY_EMULATED_IDENTITY_URL and NETLIFY_LAMBDA_LOCALLY_EMULATED_IDENTITY_TOKEN. In production, of course, Netlify Functions will give you the correct identity.url and identity.token fields. We find we dont use this info often in our functions so it is not that big of a deal in our judgment.

Debugging

To debug lambdas, it can be helpful to turn off minification and enable logging. Prepend the serve command with npm's package runner npx, e.g. npx --node-arg=--inspect netlify-lambda serve ....

1. make sure that sourcemaps are built along the way (e.g. in the webpack configuration and the tsconfig.json if typescript is used)
2. webpack's minification/uglification is turned off (see below):

For example, to customize the webpack config you can have a file with:

// webpack.functions.js
module.exports = {
  optimization: { minimize: false }
};

You can see a sample project with this setup here.

So you can run something like npx --node-arg=--inspect netlify-lambda serve --config ./webpack.functions.js. If using VSCode, it is likely that the sourceMapPathOverrides have to be adapted for breakpoints to work. Read here for more info on how to modify the webpack config.

Netlify Functions run in Node v8.10 and you may need to run the same version to mirror the environment locally. Also make sure to check that you aren't committing one of these common Node 8 mistakes in Lambda!

Special warning on node-fetch: node-fetch and webpack currently don't work well together. You will have to use the default export in your code:

const fetch = require("node-fetch").default; // not require('node-fetch')

Don't forget to search our issues in case someone has run into a similar problem you have!

Example functions and Tutorials

You can do a great deal with lambda functions! Here are some examples for inspiration:

• Basic Netlify Functions tutorial: https://flaviocopes.com/netlify-functions/
• Netlify's list of Function examples: https://functions-playground.netlify.com/ (Even more in the README as well as our full list https://functions.netlify.com/examples/)
• Slack Notifications: https://css-tricks.com/forms-auth-and-serverless-functions-on-gatsby-and-netlify/#article-header-id-9
• URL Shortener: https://www.netlify.com/blog/2018/03/19/create-your-own-url-shortener-with-netlifys-forms-and-functions/
• Gatsby + Netlify Identity + Functions: Turning the Static Dynamic: Gatsby + Netlify Functions + Netlify Identity
• Raymond Camden's Adding Serverless Functions to Your Netlify Static Site
• Travis Horn's Netlify Lambda Functions from Scratch
• JAMstack with Divya Sasidharan & Phil Hawksworth | Devchat.tv - Great discussion on the problems that Netlify Functions solve
• Netlify function error reporting with Sentry - automatic error reporting for your Netlify functions, so you know any time they fail.
• React + Stripe + Netlify Functions: Build and deploy a serverless eCommerce project
• Submit your blogpost here!

These libraries pair very well for extending your functions capability:

• Middleware: https://github.com/middyjs/middy
• GraphQL: https://www.npmjs.com/package/apollo-server-lambda
• Any others to suggest?

Other community approaches

If you wish to serve the full website from lambda, check this issue.

If you wish to run this server for testing, check this issue.

If you wish to emulate more Netlify functionality locally, check this repo: https://github.com/8eecf0d2/netlify-local. We are considering merging the projects here.

All of the above are community maintained and not officially supported by Netlify.

Changelog

• v1.0: https://twitter.com/Netlify/status/1050399820484087815 Webpack 4 and Babel 7
• v1.1: https://twitter.com/swyx/status/1069544181259849729 Typescript support
• v1.2: https://twitter.com/swyx/status/1083446733374337024 Identity emulation (& others)
• v1.3: https://github.com/netlify/netlify-lambda/releases/tag/v1.3.0
• v1.4: New timeout feature https://github.com/netlify/netlify-lambda/pull/116
• v1.5: Catch raw requests - a very common error for first time users pinging localhost:9000 instead of localhost:9000/.netlify/functions/myfunction https://github.com/netlify/netlify-lambda/commit/bfebc0921a45d4f730b910b680e40e04928f7c29#diff-3288939317efd62bfc509440d662cacaR191
• v1.6: New install command https://mobile.twitter.com/swyx/status/1162038490298818562

License

MIT