Merge pull request #144 from elastic-coders/update-serverless-offline-docs

Update docs for use with serverless-offline

Author: HyperBrain

README.md

@@ -122,33 +122,49 @@ The normal Serverless deploy procedure will automatically bundle with Webpack:
 - Install Serverless Webpack as above
 - Deploy with `serverless deploy`
 
-### Simulate API Gateway locally
+### Usage with serverless-offline
 
-To start a local server that will act like the API Gateway use the following command.
-Your code will be reloaded upon change so that every request to your local server
-will serve the latest code.
+The plugin integrates very well with [serverless-offline][link-serverless-offline] to
+simulate AWS Lambda and AWS API Gateway locally.
 
-```bash
-$ serverless webpack serve
+Add the plugins to your `serverless.yml` file and make sure that `serverless-webpack`
+precedes `serverless-offline` as the order is important:
+```yaml
+  plugins:
+    ...
+    - serverless-webpack
+    ...
+    - serverless-offline
+    ...
 ```
 
-Options are:
+Run `serverless offline` or `serverless offline start` to start the Lambda/API simulation.
 
-- `--port` or `-p` (optional) The local server port. Defaults to `8000`
+In comparison to `serverless offline`, the `start` command will fire an `init` and a `end` lifecycle hook which is needed for `serverless-offline` and e.g. `serverless-dynamodb-local` to switch off resources (see below).
 
-The `serve` command will automatically look for the local `serverless.yml` and serve
-all the `http` events. For example this configuration will generate a GET endpoint:
+#### Custom paths
 
+If you do not use the default path and override it in your Webpack configuration,
+you have use the `--location` option.
+
+#### serverless-dynamodb-local
+
+Configure your service the same as mentioned above, but additionally add the `serverless-dynamodb-local`
+plugin as follows:
 ```yaml
-functions:
-  hello:
-    handler: handler.hello
-    events:
-      - http:
-          method: get
-          path: hello
+  plugins:
+    - serverless-webpack
+    - serverless-dynamodb-local
+    - serverless-offline
 ```
 
+Run `serverless offline start`.
+
+#### Other useful options
+
+You can reduce the clutter generated by `serverless-offline` with `--dontPrintOutput` and
+disable timeouts with `--noTimeout`.
+
 ### Run a function locally
 
 To run your bundled functions locally you can:
@@ -175,18 +191,6 @@ Options are:
 - `--function` or `-f` (required) is the name of the function to run
 - `--path` or `-p` (optional) is a JSON file path used as the function input event
 
-### Using with serverless-offline and serverless-webpack plugin
-
- Run `serverless offline start`. In comparison with `serverless offline`, the `start` command will fire an `init` and a `end` lifecycle hook which is needed for serverless-offline and serverless-dynamodb-local to switch off both resources. 
- 
- Add plugins to your `serverless.yml` file:
- ```yaml
- plugins:
-   - serverless-webpack
-   - serverless-dynamodb-local
-   - serverless-offline #serverless-offline needs to be last in the list
- ```
-
 ### Bundle with webpack
 
 To just bundle and see the output result use:
@@ -199,6 +203,38 @@ Options are:
 
 - `--out` or `-o` (optional) The output directory. Defaults to `.webpack`.
 
+### Simulate API Gateway locally
+
+_There are plans to remove the integrated simulation functionality in favor of
+using serverless-offline (see [#135](https://github.com/elastic-coders/serverless-webpack/issues/135))
+which already does the job perfectly and fully integrates with serverless-webpack.
+Please consider to switch to serverless-offline if you do not use it already._
+
+To start a local server that will act like the API Gateway use the following command.
+Your code will be reloaded upon change so that every request to your local server
+will serve the latest code.
+
+```bash
+$ serverless webpack serve
+```
+
+Options are:
+
+- `--port` or `-p` (optional) The local server port. Defaults to `8000`
+
+The `serve` command will automatically look for the local `serverless.yml` and serve
+all the `http` events. For example this configuration will generate a GET endpoint:
+
+```yaml
+functions:
+  hello:
+    handler: handler.hello
+    events:
+      - http:
+          method: get
+          path: hello
+```
+
 ## Example with Babel
 
 In the [`examples`][link-examples] folder there is a Serverless project using this
@@ -223,3 +259,5 @@ plugin with Babel. To try it, from inside the example folder:
 [link-webpack-libtarget]: https://webpack.github.io/docs/configuration.html#output-librarytarget
 [link-webpack-externals]: https://webpack.github.io/docs/configuration.html#externals
 [link-examples]: ./examples
+[link-serverless-offline]: https://www.npmjs.com/package/serverless-offline
+[link-serverless-dynamodb-local]: https://www.npmjs.com/package/serverless-dynamodb-local