Giters

chrbala / netlify-lambda

Helps building and serving lambda functions locally and in CI environments

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Netlify Lambda

This is an optional tool that helps with building or locally developing Netlify Functions with a simple webpack/babel build step.

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

Installation

We recommend installing locally rather than globally: yarn add -D 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.

Usage

We expose two commands:

netlify-lambda serve <folder>
netlify-lambda build <folder>

The serve function will start a dev server and a file watcher for the specified folder and route requests to the relevant function at:

http://localhost:9000/hello -> folder/hello.js (must export a handler(event, context callback) function)

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

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.
  • 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.

There are additional CLI options, introduced below:

-h --help
-c --config
-p --port
-s --static

Using with create-react-app, Gatsby, and other development servers

react-scripts (the underlying library for create-react-app) and other popular development servers often set up catchall serving for you; in other words, if you try to request a route that doesn't exist, the dev server will try to serve you /index.html. This is problematic when you are trying to hit a local API endpoint like netlify-lambda sets up for you - your browser will attempt to parse the index.html file as JSON. This is why you may see this error:

Uncaught (in promise) SyntaxError: Unexpected token < in JSON at position 0

If this desribes your situation, then you need to proxy for local development. Read on. Don't worry it's easier than it looks.

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.

Example webpack config:

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

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

**Using with `Angular CLI`**

CORS issues when trying to use netlify-lambdas locally with angular? you need to set up a proxy.

Firstly make sure you are using relative paths in your app to ensure that your app will work locally and on Netlify, example below...

  this.http.get('/.netlify/functions/jokeTypescript')

Then place a proxy.config.json file in the root of your project, the contents should look something like...

{
  "/.netlify/functions/*": {
    "target": "http://localhost:9000",
    "secure": false,
    "logLevel": "debug",
    "changeOrigin": true
  }
}
  • The key should match up with the location of your Transpiled functions as defined in your netlify.toml
  • The target should match the port that the lambdas are being served on (:9000 by default)

When you run up your Angular project you need to pass in the proxy config with the flag --proxy-config like so...

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

To make your life easier you can add these to your scripts in package.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"
  }

Obviously you need to run up netlify-lambda & angular at the same time.

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. See this issue for an example of how to write a webpack override file.

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, it will be used instead of the default one. 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",
      {
        "targets": {
          "node": "6.10.3"
        }
      }
    ]
  ],
  "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.

--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.

Debugging

To debug lambdas, prepend the serve command with npm's package runner npx npx --node-arg=--inspect netlify-lambda serve .... Additionally:

  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 uglification is turned off with optimization: { minimize: false }. If using VSCode, it is likely that the sourceMapPathOverrides have to be adapted for breakpoints to work.

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!

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

Netlify Identity

Netlify Identity is not supported at the moment inside netlify-lambda function emulation, but for now you can read the docs on how they should work.

Example functions and Tutorials

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

These libraries pair very well for extending your functions capability:

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.

License

MIT

About

Helps building and serving lambda functions locally and in CI environments

Languages

Language:JavaScript 100.0%