|
| 1 | +# Serverless Node.js Starter [](https://console.seed.run/serverless-stack/serverless-nodejs-starter) |
| 2 | + |
| 3 | +A Serverless starter that adds ES6, TypeScript, serverless-offline, linting, environment variables, and unit test support. Part of the [Serverless Stack](http://serverless-stack.com) guide. |
| 4 | + |
| 5 | +[Serverless Node.js Starter](https://github.com/AnomalyInnovations/serverless-nodejs-starter) uses the [serverless-bundle](https://github.com/AnomalyInnovations/serverless-bundle) plugin and the [serverless-offline](https://github.com/dherault/serverless-offline) plugin. It supports: |
| 6 | + |
| 7 | +- **Generating optimized Lambda packages with Webpack** |
| 8 | +- **Using ES6 or TypeScript in your handler functions** |
| 9 | +- **Run API Gateway locally** |
| 10 | + - Use `serverless offline start` |
| 11 | +- **Support for unit tests** |
| 12 | + - Run `npm test` to run your tests |
| 13 | +- **Sourcemaps for proper error messages** |
| 14 | + - Error message show the correct line numbers |
| 15 | + - Works in production with CloudWatch |
| 16 | +- **Lint your code with ESLint** |
| 17 | +- **Add environment variables for your stages** |
| 18 | +- **No need to manage Webpack or Babel configs** |
| 19 | + |
| 20 | +--- |
| 21 | + |
| 22 | +### Demo |
| 23 | + |
| 24 | +A demo version of this service is hosted on AWS - [`https://z6pv80ao4l.execute-api.us-east-1.amazonaws.com/dev/hello`](https://z6pv80ao4l.execute-api.us-east-1.amazonaws.com/dev/hello) |
| 25 | + |
| 26 | +And here is the ES6 source behind it |
| 27 | + |
| 28 | +``` javascript |
| 29 | +export const hello = async (event, context) => { |
| 30 | + return { |
| 31 | + statusCode: 200, |
| 32 | + body: JSON.stringify({ |
| 33 | + message: `Go Serverless v1.0! ${(await message({ time: 1, copy: 'Your function executed successfully!'}))}`, |
| 34 | + input: event, |
| 35 | + }), |
| 36 | + }; |
| 37 | +}; |
| 38 | + |
| 39 | +const message = ({ time, ...rest }) => new Promise((resolve, reject) => |
| 40 | + setTimeout(() => { |
| 41 | + resolve(`${rest.copy} (with a delay)`); |
| 42 | + }, time * 1000) |
| 43 | +); |
| 44 | +``` |
| 45 | + |
| 46 | +### Upgrading from v1.x |
| 47 | + |
| 48 | +We have detailed instructions on how to upgrade your app to the v2.0 of the starter if you were using v1.x before. [Read about it here](https://github.com/AnomalyInnovations/serverless-nodejs-starter/releases/tag/v2.0). |
| 49 | + |
| 50 | +### Requirements |
| 51 | + |
| 52 | +- [Install the Serverless Framework](https://serverless.com/framework/docs/providers/aws/guide/installation/) |
| 53 | +- [Configure your AWS CLI](https://serverless.com/framework/docs/providers/aws/guide/credentials/) |
| 54 | + |
| 55 | +### Installation |
| 56 | + |
| 57 | +To create a new Serverless project. |
| 58 | + |
| 59 | +``` bash |
| 60 | +$ serverless install --url https://github.com/AnomalyInnovations/serverless-nodejs-starter --name my-project |
| 61 | +``` |
| 62 | + |
| 63 | +Enter the new directory |
| 64 | + |
| 65 | +``` bash |
| 66 | +$ cd my-project |
| 67 | +``` |
| 68 | + |
| 69 | +Install the Node.js packages |
| 70 | + |
| 71 | +``` bash |
| 72 | +$ npm install |
| 73 | +``` |
| 74 | + |
| 75 | +### Usage |
| 76 | + |
| 77 | +To run a function on your local |
| 78 | + |
| 79 | +``` bash |
| 80 | +$ serverless invoke local --function hello |
| 81 | +``` |
| 82 | + |
| 83 | +To simulate API Gateway locally using [serverless-offline](https://github.com/dherault/serverless-offline) |
| 84 | + |
| 85 | +``` bash |
| 86 | +$ serverless offline start |
| 87 | +``` |
| 88 | + |
| 89 | +Deploy your project |
| 90 | + |
| 91 | +``` bash |
| 92 | +$ serverless deploy |
| 93 | +``` |
| 94 | + |
| 95 | +Deploy a single function |
| 96 | + |
| 97 | +``` bash |
| 98 | +$ serverless deploy function --function hello |
| 99 | +``` |
| 100 | + |
| 101 | +#### Running Tests |
| 102 | + |
| 103 | +Run your tests using |
| 104 | + |
| 105 | +``` bash |
| 106 | +$ npm test |
| 107 | +``` |
| 108 | + |
| 109 | +We use Jest to run our tests. You can read more about setting up your tests [here](https://facebook.github.io/jest/docs/en/getting-started.html#content). |
| 110 | + |
| 111 | +#### Environment Variables |
| 112 | + |
| 113 | +To add environment variables to your project |
| 114 | + |
| 115 | +1. Rename `env.example` to `.env`. |
| 116 | +2. Add environment variables for your local stage to `.env`. |
| 117 | +3. Uncomment `environment:` block in the `serverless.yml` and reference the environment variable as `${env:MY_ENV_VAR}`. Where `MY_ENV_VAR` is added to your `.env` file. |
| 118 | +4. Make sure to not commit your `.env`. |
| 119 | + |
| 120 | +#### TypeScript |
| 121 | + |
| 122 | +If [serverless-bundle](https://github.com/AnomalyInnovations/serverless-bundle) detects a `tsconfig.json` in your service root, it'll compile it using TypeScript. We have a separate starter for TypeScript here, [**Serverless TypeScript Starter**](https://github.com/AnomalyInnovations/serverless-typescript-starter). |
| 123 | + |
| 124 | +#### Linting |
| 125 | + |
| 126 | +We use [ESLint](https://eslint.org) to lint your code via [serverless-bundle](https://github.com/AnomalyInnovations/serverless-bundle). |
| 127 | + |
| 128 | +You can turn this off by adding the following to your `serverless.yml`. |
| 129 | + |
| 130 | +``` yaml |
| 131 | +custom: |
| 132 | + bundle: |
| 133 | + linting: false |
| 134 | +``` |
| 135 | +
|
| 136 | +To [override the default config](https://eslint.org/docs/user-guide/configuring), add a `.eslintrc.json` file. To ignore ESLint for specific files, add it to a `.eslintignore` file. |
| 137 | + |
| 138 | +### Support |
| 139 | + |
| 140 | +- Open a [new issue](https://github.com/AnomalyInnovations/serverless-nodejs-starter/issues/new) if you've found a bug or have some suggestions. |
| 141 | +- Or submit a pull request! |
| 142 | + |
| 143 | +--- |
| 144 | + |
| 145 | +This repo is maintained by [Serverless Stack](https://serverless-stack.com). |
0 commit comments