This is a small CLI tool that helps with building or serving lambdas built with a simple webpack/babel setup.
The goal is to make it easy to work with Lambda's with modern ES6 without being dependent on having the most state of the art node runtime available in the final deployment environment and with a build that can compile all modules into a single lambda file.
Since v1.0.0 the dependencies were upgraded to Webpack 4 and Babel 7.
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).
Netlify lambda installs two commands:
netlify-lambda serve <folder>
netlify-lambda build <folder>
IMPORTANT: Both commands depend on a netlify.toml
file being present in your project and configuring functions for deployment.
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.
There are additional options, introduced later:
-h --help
-c --config
-p --port
-s --static
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.
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.
- 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. - If you are using Gatsby, see their Advanced Proxying docs
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.
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 Transpiledfunctions
as defined in yournetlify.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.
To debug lambdas, prepend the serve
command with npm's package runner npx npx --node-arg=--inspect netlify-lambda serve ...
. Additionally, make sure that sourcemaps are built along the way (e.g. in the webpack configuration and the tsconfig.json
if typescript is used) and 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.
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.
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.
We added .ts
and .mjs
support recently - check here for the PR and usage tips.
- Install
@babel/preset-typescript
npm install --save-dev @babel/preset-typescript
- Create custom
.babelrc
.
{
"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"
]
}
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.
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) and (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 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.
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.
All of the above are community maintained and not officially supported by Netlify.