Skip to content

Commit c3e01fd

Browse files
author
sw-yx
committed
readme
1 parent 9bd22e6 commit c3e01fd

File tree

1 file changed

+48
-28
lines changed

1 file changed

+48
-28
lines changed

Diff for: ‎README.md

+48-28
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
## Netlify Lambda
22

3-
This is an optional tool that helps with building or locally developing [Netlify Functions](https://www.netlify.com/docs/functions/) with a simple webpack/babel build step.
3+
This is an optional tool that helps with building or locally developing [Netlify Functions](https://www.netlify.com/docs/functions/) with a simple webpack/babel build step. For function folders, there is also a small utility to install function folder dependencies.
44

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

@@ -15,9 +15,9 @@ There are 3 ways to deploy functions to Netlify:
1515

1616
`Netlify-Lambda` uses webpack to bundle up your functions and their dependencies for you, suiting the first approach. However, if you have native node modules (or other dependencies that don't expect to be bundled like [the Firebase SDK](https://github.com/netlify/netlify-lambda/issues/112)) then you may want to try the other approaches. In particular, try [`Netlify Dev`](https://github.com/netlify/netlify-dev-plugin#what-is-netlify-dev).
1717

18-
If this sounds confusing, support is available through [our regular channels](https://www.netlify.com/support/).
19-
</details>
18+
If this sounds confusing, support is available through [our regular channels](https://www.netlify.com/support/).
2019

20+
</details>
2121

2222
<details>
2323
<summary><b>Netlify Dev vs. Netlify-Lambda</b></summary>
@@ -26,16 +26,14 @@ If this sounds confusing, support is available through [our regular channels](ht
2626

2727
[`Netlify Dev`](https://github.com/netlify/netlify-dev-plugin#what-is-netlify-dev) is incrementally adoptable. **`netlify-lambda` is still recommended if you need a build step for your functions**, as explained here:
2828

29-
- **When to use Netlify Dev**: Part of Netlify Dev serves unbundled function folders through [zip-it-and-ship-it](https://github.com/netlify/zip-it-and-ship-it) with no build step. This is likely to be attractive to many users who previously just needed `netlify-lambda` for bundling multi-file functions or functions with node_module dependencies.
29+
- **When to use Netlify Dev**: Part of Netlify Dev serves unbundled function folders through [zip-it-and-ship-it](https://github.com/netlify/zip-it-and-ship-it) with no build step. This is likely to be attractive to many users who previously just needed `netlify-lambda` for bundling multi-file functions or functions with node_module dependencies.
3030
- **When to use Netlify Lambda**: However, if you need a build step for your functions (e.g. for webpack import/export syntax, running babel transforms or typescript), you can use `netlify-lambda`, `tsc` or your own build tool to do this, just point Netlify Dev at your build output with the `functions` field in `netlify.toml`.
3131
- These responsibilities aren't exactly the same. Therefore **you can use Netlify Dev and Netlify Lambda together** to have BOTH a build step for functions from `netlify-lambda` and the full proxy environment from Netlify Dev. If you have a npm script in `package.json` for running `netlify-lambda serve ${functionsSourceFolder}`, Netlify Dev will [detect it](https://github.com/netlify/netlify-dev-plugin#function-builders-function-builder-detection-and-relationship-with-netlify-lambda) and run it for you. This way, **existing `netlify-lambda` users will be able to use Netlify Dev with no change to their workflow**
3232

3333
Function Builder detection is a very new feature with only simple detection logic for now, that we aim to improve over time. If it doesn't work well for you, you can simply not use Netlify Dev for now while we work out all your bug reports. 🙏🏼
3434

3535
</details>
3636

37-
38-
3937
## Installation
4038

4139
**We recommend installing locally** rather than globally:
@@ -58,13 +56,36 @@ If you don't have a [`netlify.toml`](https://www.netlify.com/docs/netlify-toml-r
5856

5957
## Usage
6058

61-
We expose two commands:
59+
We expose three commands:
6260

63-
```
61+
```bash
6462
netlify-lambda serve <folder>
6563
netlify-lambda build <folder>
64+
netlify-lambda install [folder]
65+
```
66+
67+
### `netlify-lambda install`
68+
69+
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.
70+
71+
By default it just runs on the functions folder specified in `netlify.toml`:
72+
73+
```bash
74+
netlify-lambda install
75+
```
76+
77+
This is what you should do if you are just using Netlify Dev without `netlify-lambda`.
78+
79+
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:
80+
81+
```bash
82+
netlify-lambda install <folderName>
6683
```
6784

85+
We don't anticipate you will use this as often but it can be handy.
86+
87+
### `netlify-lambda serve` and `netlify-lambda build`
88+
6889
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).
6990

7091
The `build` function will run a single build of the functions in the folder.
@@ -164,12 +185,12 @@ Say you are running `webpack-serve` on port 8080 and `netlify-lambda serve` on p
164185

165186
```js
166187
module.exports = {
167-
mode: 'development',
188+
mode: "development",
168189
devServer: {
169190
proxy: {
170-
'/.netlify': {
171-
target: 'http://localhost:9000',
172-
pathRewrite: { '^/.netlify/functions': '' }
191+
"/.netlify": {
192+
target: "http://localhost:9000",
193+
pathRewrite: { "^/.netlify/functions": "" }
173194
}
174195
}
175196
}
@@ -186,7 +207,7 @@ CORS issues when trying to use netlify-lambdas locally with angular? you need to
186207
Firstly make sure you are using relative paths in your app to ensure that your app will work locally and on Netlify, example below...
187208

188209
```js
189-
this.http.get('/.netlify/functions/jokeTypescript');
210+
this.http.get("/.netlify/functions/jokeTypescript");
190211
```
191212

192213
Then place a `proxy.config.json` file in the root of your project, the contents should look something like...
@@ -240,21 +261,21 @@ yarn add -D http-proxy-middleware express
240261
```js
241262
// server.js
242263
/* eslint-disable no-console */
243-
const express = require('express');
244-
const next = require('next');
264+
const express = require("express");
265+
const next = require("next");
245266

246267
const devProxy = {
247-
'/.netlify': {
248-
target: 'http://localhost:9000',
249-
pathRewrite: { '^/.netlify/functions': '' }
268+
"/.netlify": {
269+
target: "http://localhost:9000",
270+
pathRewrite: { "^/.netlify/functions": "" }
250271
}
251272
};
252273

253274
const port = parseInt(process.env.PORT, 10) || 3000;
254275
const env = process.env.NODE_ENV;
255-
const dev = env !== 'production';
276+
const dev = env !== "production";
256277
const app = next({
257-
dir: '.', // base directory where everything is, could move to src later
278+
dir: ".", // base directory where everything is, could move to src later
258279
dev
259280
});
260281

@@ -268,14 +289,14 @@ app
268289

269290
// Set up the proxy.
270291
if (dev && devProxy) {
271-
const proxyMiddleware = require('http-proxy-middleware');
292+
const proxyMiddleware = require("http-proxy-middleware");
272293
Object.keys(devProxy).forEach(function(context) {
273294
server.use(proxyMiddleware(context, devProxy[context]));
274295
});
275296
}
276297

277298
// Default catch-all handler to allow Next.js to handle all other routes
278-
server.all('*', (req, res) => handle(req, res));
299+
server.all("*", (req, res) => handle(req, res));
279300

280301
server.listen(port, err => {
281302
if (err) {
@@ -285,10 +306,9 @@ app
285306
});
286307
})
287308
.catch(err => {
288-
console.log('An error occurred, unable to start the server');
309+
console.log("An error occurred, unable to start the server");
289310
console.log(err);
290311
});
291-
292312
```
293313

294314
run your server and netlify-lambda at the same time:
@@ -347,9 +367,9 @@ The additional webpack config will be merged into the default config via [webpac
347367

348368
The default webpack configuration uses `babel-loader` with a [few basic settings](https://github.com/netlify/netlify-lambda/blob/master/lib/build.js#L19-L33).
349369

350-
However, if any `.babelrc` is found in the directory `netlify-lambda` is run from, or [folders above it](https://github.com/netlify/netlify-lambda/pull/92) (useful for monorepos), it will be used instead of the default one.
370+
However, if any `.babelrc` is found in the directory `netlify-lambda` is run from, or [folders above it](https://github.com/netlify/netlify-lambda/pull/92) (useful for monorepos), it will be used instead of the default one.
351371

352-
It is possible to disable this behaviour by passing `--babelrc false`.
372+
It is possible to disable this behaviour by passing `--babelrc false`.
353373

354374
If you need to run different babel versions for your lambda and for your app, [check this issue](https://github.com/netlify/netlify-lambda/issues/34) to override your webpack babel-loader.
355375

@@ -441,7 +461,7 @@ Minor note: For the `identity` field, since we are not fully emulating Netlify I
441461

442462
## Debugging
443463

444-
To debug lambdas, it can be helpful to turn off minification and enable logging. Prepend the `serve` command with [npm's package runner npx](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b), e.g. `npx --node-arg=--inspect netlify-lambda serve ...`.
464+
To debug lambdas, it can be helpful to turn off minification and enable logging. Prepend the `serve` command with [npm's package runner npx](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b), e.g. `npx --node-arg=--inspect netlify-lambda serve ...`.
445465

446466
1. make sure that sourcemaps are built along the way (e.g. in the webpack configuration and the `tsconfig.json` if typescript is used)
447467
2. webpack's minification/uglification is turned off (see below):
@@ -464,7 +484,7 @@ Netlify Functions [run in Node v8.10](https://www.netlify.com/blog/2018/04/03/no
464484
**Special warning on `node-fetch`**: `node-fetch` and webpack [currently don't work well together](https://github.com/bitinn/node-fetch/issues/450). You will have to use the default export in your code:
465485

466486
```js
467-
const fetch = require('node-fetch').default // not require('node-fetch')
487+
const fetch = require("node-fetch").default; // not require('node-fetch')
468488
```
469489

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

0 commit comments

Comments
 (0)