├── .gitignore ├── LICENSE ├── README.md ├── env.example ├── handler.js ├── package-lock.json ├── package.json ├── serverless.yml └── tests └── handler.test.js /.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | logs 3 | *.log 4 | npm-debug.log* 5 | 6 | # Runtime data 7 | pids 8 | *.pid 9 | *.seed 10 | 11 | # Directory for instrumented libs generated by jscoverage/JSCover 12 | lib-cov 13 | 14 | # Coverage directory used by tools like istanbul 15 | coverage 16 | 17 | # nyc test coverage 18 | .nyc_output 19 | 20 | # Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files) 21 | .grunt 22 | 23 | # node-waf configuration 24 | .lock-wscript 25 | 26 | # Compiled binary addons (http://nodejs.org/api/addons.html) 27 | build/Release 28 | 29 | # Dependency directories 30 | node_modules 31 | jspm_packages 32 | 33 | # Optional npm cache directory 34 | .npm 35 | 36 | # Optional REPL history 37 | .node_repl_history 38 | 39 | # vim 40 | .*.sw* 41 | Session.vim 42 | 43 | # Serverless 44 | .webpack 45 | .serverless 46 | 47 | # env 48 | env.yml 49 | .env 50 | 51 | # Jetbrains IDEs 52 | .idea 53 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2017 Anomaly Innovations 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Serverless Node.js Starter [![Seed Status](https://api.seed.run/serverless-stack/serverless-nodejs-starter/stages/prod/build_badge)](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). 146 | -------------------------------------------------------------------------------- /env.example: -------------------------------------------------------------------------------- 1 | # HOW TO USE: 2 | # 3 | # 1 Add environment variables for local development. 4 | # 2 Rename this file to .env and uncomment it's usage 5 | # in the serverless.yml. 6 | # 3 Make sure to not commit this file. 7 | 8 | SAMPLE_ENV_VAR=i-am-an-environment-variable 9 | -------------------------------------------------------------------------------- /handler.js: -------------------------------------------------------------------------------- 1 | export const hello = async (event, context) => { 2 | return { 3 | statusCode: 200, 4 | body: JSON.stringify({ 5 | message: `Go Serverless v2.0! ${(await message({ time: 1, copy: 'Your function executed successfully!'}))}`, 6 | }), 7 | }; 8 | }; 9 | 10 | const message = ({ time, ...rest }) => new Promise((resolve, reject) => 11 | setTimeout(() => { 12 | resolve(`${rest.copy} (with a delay)`); 13 | }, time * 1000) 14 | ); 15 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "serverless-nodejs-starter", 3 | "version": "2.2.0", 4 | "description": "A Node.js starter for Serverless Framework with ES6 and TypeScript support", 5 | "main": "handler.js", 6 | "scripts": { 7 | "test": "serverless-bundle test" 8 | }, 9 | "author": "", 10 | "license": "MIT", 11 | "repository": { 12 | "type": "git", 13 | "url": "https://github.com/AnomalyInnovations/serverless-nodejs-starter.git" 14 | }, 15 | "devDependencies": { 16 | "serverless-bundle": "4.3.1", 17 | "serverless-dotenv-plugin": "^2.1.1", 18 | "serverless-offline": "^5.3.3" 19 | }, 20 | "dependencies": {} 21 | } 22 | -------------------------------------------------------------------------------- /serverless.yml: -------------------------------------------------------------------------------- 1 | # NOTE: update this with your service name 2 | service: serverless-nodejs-starter 3 | 4 | # Create an optimized package for our functions 5 | package: 6 | individually: true 7 | 8 | plugins: 9 | - serverless-bundle # Package our functions with Webpack 10 | - serverless-offline 11 | - serverless-dotenv-plugin # Load .env as environment variables 12 | 13 | provider: 14 | name: aws 15 | runtime: nodejs10.x 16 | stage: dev 17 | region: us-east-1 18 | # To load environment variables externally 19 | # rename env.example to .env and uncomment 20 | # the following line. Also, make sure to not 21 | # commit your .env. 22 | # 23 | #environment: 24 | # SAMPLE_ENV_VAR: ${env:SAMPLE_ENV_VAR} 25 | 26 | functions: 27 | hello: 28 | handler: handler.hello 29 | events: 30 | - http: 31 | path: hello 32 | method: get 33 | -------------------------------------------------------------------------------- /tests/handler.test.js: -------------------------------------------------------------------------------- 1 | import * as handler from '../handler'; 2 | 3 | test('hello', async () => { 4 | const event = 'event'; 5 | const context = 'context'; 6 | const callback = (error, response) => { 7 | expect(response.statusCode).toEqual(200); 8 | expect(typeof response.body).toBe("string"); 9 | }; 10 | 11 | await handler.hello(event, context, callback); 12 | }); 13 | --------------------------------------------------------------------------------