README.md

Netlify Local

Local Netlify service emulation.

Experimental: This package has not been heavily tested or used, some of the Netlify Services are incorrectly implemented. Submit an issue if you find any!

Semver Notice: Breaking changes which increase compatibility with Netlify services and features are not considered breaking 🤷‍♂️

For help bundling your Javascript to work with Netlify Functions, checkout netlify/netlify-lambda or 8eecf0d2/webpack-netlify-lambda-plugin.

An example Netlify deployable application is available at 8eecf0d2/netlify-local-example.

Install

You should probably install as a dev dependency, but globally works too.

yarn add -D netlify-local

Usage

serve command

The serve command will attempt to emulate Netlify Services.

netlify-local serve <options>

build command

The build command will attempt to correctly execute the build.command property within netlify.toml.

netlify-local build <options>

bundle command

The bundle command will attempt to parse your netlify.toml and build a Webpack Configuration with the correct entry and output properties before running a Webpack compiler with the computed configuration.

netlify-local bundle <options>

Options

You can view a detailed list of options in the wiki.

Features

Static Router

The static router refers to the static server functionality of Netlify Continuous Deployment, which serves files from the build.publish directory, specified within the toml configuration.

Lambda Router

The lambda router refers to the Netlify Functions feature which serves Lambda's or Cloud Functions from the build.functions directory, specified within the toml configuration.

Redirects

This feature refers to Netlify Redirects, this has not been correctly implemented and is missing a lot of functionality, see Issue #8 for progress.

Headers

This feature refers to Netlify Headers, for the most part this works as expected however the Netlify Basic Auth portion is not supported.

API

Specific classes and methods are exposed for running netlify-local programmatically, see Issue #6 for more information and documentation.

Typings

Relevant Typescript typings are exposed for the API and also Netlify Function handlers.

import { Netlify } from "netlify-local";

export const handler: Netlify.Handler<handler.Request, handler.Context, handler.Response> = (request, context, callback) => {

  return callback(null, {
    statusCode: 200,
    body: "foo"
  })
}

export namespace handler {
  export interface Request extends Netlify.Handler.Request {
    headers: {
      example: string;
    }
  }
  export interface Context extends Netlify.Handler.Context {
    user: { ... }
  }
  export interface Response extends Netlify.Handler.Response {
    body: { ... };
  }
}

Webpack

Multiple Configs

If you use multiple Webpack configurations for your application (one for the client, another for lambda) you should set the name property within the Webpack configuration to get better logging, otherwise config's will be named by their index.

Issues

To correctly execute lambda's they must be self contained bundles, a common issue when bundled incorrectly is missing modules similar to the error below.

Error: Cannot find module '/.../path/file'

To bundle your files correctly ensure that module.exports.handler is exposed for each handler file and that you're using individual entires within webpack.

module.exports = {
  target: "node",
  entry: {
    foo: "./src/ts/handlers/foo.ts",
    bar: "./src/ts/handlers/bar.ts",
    ...
  },
  ...
}

If you're starting a new project or not currently bundling, the easiest solution would be to use netlify/netlify-lambda and it's build command.

If you've got a pre-existing webpack config I'd suggest using a webpack helper library such as 8eecf0d2/webpack-netlify-lambda-plugin.

Credit

This project is inspired by netlify/netlify-lambda.