It’s time again. Serverless v1 beta.2 was released nearly two weeks ago. Today we’re happy and proud to announce the first release candidate of the Serverless Framework v1 (Serverless v1 rc.1). You can install it via:
npm install -g serverless@1.0.0-rc.1This release candidate comes with many new features, bug fixes and improvements. Before jumping into the details about what’s changed we’d like to tip our virtual hats and say thank you to our awesome community / contributors. The huge number of new features wouldn’t have been possible without each one of you. We’re happy to have all of you aboard and excited about the future of Serverless we’ll build together! Alright. Let’s take a look at all the new features in detail!
Renaming of resources logical IDs (BREAKING CHANGE)
See #1869, #1828, #1672, #1842, #1823, #1907, #1924, #1931, #1950, #1960 and #1951 The deployment via CloudFormation makes it necessary for Serverless to generate logical ids for all the resources which are created on your behalf (e.g. resources which are used to setup your API Gateway with the help of the http event). Serverless also supports custom resources you can specify in the resources section of the serverless.yml file. Advanced usage and requirements made it necessary to change the merging logic of these custom resources so that you’re able to e.g. overwrite the resources which are generated by Serverless using the custom provider resources. This new resource merging strategy was implemented in the last release (Serverless v1 beta.2). A problem which still persisted since then was that the logical ids of the resources Serverless created were hard to predict and use to overwrite specific behavior. Thanks to the great discussions we came to a predictable rule we’ll now follow to generate the resource logical ids. You can read more about the rule here. The new naming makes it way easier for developers to overwrite or extend resources generated by Serverless. Furthermore, several bugs (such as using one S3 bucket / SNS topic in several events) were resolved alongside! Note that this is a breaking change as existing services which access resources generated by Serverless need updates to work after updating. For example, if you deploy your existing service the Lambda Function Resource can’t be created as the logical id changed, but the function name is the same (and has to be unique) so CloudFormation will fail. If you can, simply remove the existing stack and create a new one. In case this is not an option make sure to slowly update your stack and check the changes that have been happening during the deployment. Another change is that the API Gateway endpoint will change and you will get a new API Gateway for this deployment. In the event that you point something to that APIG endpoint make sure to update it. Thanks to Tapio Kukkonen (@oipat), @sung-hwang-zocdoc, Rogelio (@rogemita), Benny Bauer (@bennybauer), Timothy Caraballo (@openback) and Xavier Snelgrove (@wxs) for reporting the related bugs / helping out here!
New Serverless variable system (BREAKING CHANGE)
See #1801, #1707 and #1834 Serverless v1 was started with a powerful way to reuse configuration throughout your whole service. That’s why we introduced the serverless.env.yml file back then. However, as more and more time was spent developing real world applications with the Serverless Framework the need for an easier to understand, yet powerful and flexible way to deal with configuration / environment variables came up. We had great discussions with you about all of your needs and came up with a way to introduce a powerful, flexible and easy to understand variable system. Serverless now introduces different ways to use variables inside your service related files. Let’s take a look at some examples.
Referencing environment variables
Let’s pretend that we have exported an environment variable with the name FUNC_PREFIX and want to access this variable inside our serverless.yml file. We can do this easily like this:
service: new-service
provider: aws
functions:
hello:
name: ${env:FUNC_PREFIX}-hello
handler: handler.hello
world:
name: ${env:FUNC_PREFIX}-world
handler: handler.worldReferencing CLI options
Accessing options which might be passed through the CLI can be referenced like this:
service: new-service
provider: aws
functions:
hello:
name: ${opt:stage}-hello
handler: handler.hello
world:
name: ${opt:stage}-world
handler: handler.worldIncluding contents of other files
You can also include contents of other files like this:
service: new-service
provider: aws
custom: ${file(./myCustomFile.yml)}There are way more possibilities like nesting and combinations of all those options described above. We recommend checking out the documentation about the new variable system so that you can see how powerful it is and what you can do with it. We’d love to hear your feedback about this as this change is a crucial one! How does it behave in production-ready applications? Is something important missing? Let us know! Note that this change is a breaking change. Please check the environment variable usage of your service and note that the serverless.env.yml file has been dropped. The documentation about the new variable system will help you with the transition.
Custom request / response configuration for API Gateway
See #1593, #1968 and #1920 This was an often discussed and mentioned feature. It’s finally here thanks to the great discussion we had on how to implement it in a developer friendly way.
Request improvements
Serverless now supports two default request templates (one for the content type “application/json” and one for “application/x-www-form-urlencoded”) so that you can access all the necessary variables (e.g. like the body) inside of your functions code. Furthermore, you’re now able to set your own templates for other content types (or overwrite the default request templates) like this:
functions:
create:
handler: posts.create
events:
- http:
method: get
path: whatever
request:
template:
text/xhtml: { "stage" : "$context.stage" }
application/json: { "httpMethod" : "$context.httpMethod" }
Response improvements
Response configuration was also improved. You are now able to set custom headers and a response template when setting up your API Gateway endpoint. Let’s look at an example:
functions:
create:
handler: posts.create
events:
- http:
method: get
path: whatever
response:
headers:
Content-Type: "'text/html'"
template: $input.path('/pre>)Take a look at our new documentation for more in-depth information about request and response configuration. Note: The new variable syntax which is shown here can help you to define external request / response templates like this:
functions:
create:
handler: posts.create
events:
- http:
method: get
path: whatever
request:
template:
text/xhtml: ${file(request-template-file)}
response:
headers:
Content-Type: "'text/html'"
template: ${file(response-template-file)}Thanks to Oriol Gual (@oriolgual) for composing a request template for the content type application/x-www-form-urlencoded.
Rename service and create directory on service creation
See #1726, #1902, #1616, #1937 and #1910 The create command helps you to create and setup a service scaffold in seconds. However, it would always create the necessary files in the CWD which meant that you had to create a directory and cd into that directory if you’d like to encapsulate all your service files into a dedicated folder. After you created the service you were also forced to open up the serverless.yml file and rename it accordingly. This task is tedious and cumbersome. It would be great if Serverless could support a way a accomplish those steps in one command. The new version of Serverless adds the --path option to the create command which does exactly that. It works as follows:
serverless create --template aws-nodejs --path my-awesome-serviceThis command will create a new directory (or reuse the existing one) with the name my-awesome-service for your service, copies all the necessary files in there and renames the service in the serverless.yml file to my-awesome-service. You’re also able to specify absolute and relative paths like this:
serverless create --template aws-nodejs --path ./nested/my-awesome-serviceIn this case Serverless will create the corresponding service in the nested directory. You services name will be my-awesome-service. Thank you Vaidas Mykolaitis (@codepreneur) for reporting and Roger Lam (@mrlamroger) for working on this issue!
Show real time CloudFormation stack status
See #1818 and #1927 Sometimes it just happens. You get an error when you try to deploy your service. Serverless returns some information about a CloudFormation stack problem but you need to see the whole CloudFormation output to know what’s going on. What do you do? You open up the AWS console, navigate to the CloudFormation service, select your stack and read through the logs. We’ve all been there. While this will help you better understand the real problem, it’s still bad UX. It would be great if you could simply see the CloudFormation stack trace in your console in real time while your stack is being deployed, updated or removed. This is now a reality! Nick den Engelsman (@nicka) jumped straight into this problem and implemented this amazing and very useful feature. All you need to do is to add the --verbose flag to your serverless deploy or serverless remove commands like this:
serverless deploy --verboseThat’s it. Now you’ll see the CloudFormation outputs in real time! Nifty! 
Brand new documentation
See #1957, #1522, #1967 and #2002 A framework without a great documentation is nearly useless as nobody wants to read through the source code to see what’s possible and how to use it. However, compiling a great, easy to understand documentation is not as simple as it seems. It’s crucial to have a solid structure and also important to capture all of the details without providing unnecessary, non-relative information so that developers can have fun while building great Serverless applications. We’ve gathered a ton of feedback during our v1 journey so far from our amazing community and finally decided on a structure that will make it easy for you to follow along and see the full power the Serverless Framework provides! You can see the new documentation at docs.serverless.com. As already mentioned, great documentation is key so we’d really like to hear your feedback about the structure and the understandability! Is something missing? How can we improve here? Let us know!
Other new features, improvements and fixes
The feature set from above is just a selection of improvements we wanted to highlight. You can review each and every change of this release in our corresponding milestone. Let’s take a quick look at other features, improvements and fixes of our new release.
Individual packaging and deployment of functions
See #1777 and #1917 The ability to individually package functions is a very important feature if you want to optimize your functions to start as quickly as possible. Thanks to John McKim (@johncmckim) you now have the option to package and deploy functions independently. Check out the packaging documentation for more details.
Status code support for API Gateway
See #608 and #1998 A key feature of every HTTP API is the support for the different statuses it can get into with the help of HTTP status codes (such as e.g. 400, 404 or 500). Serverless now supports the most common HTTP status codes out of the box. The only thing you need to do is to add the corresponding status code in square brackets in the error you raise like this:
module.exports.hello = (event, context, cb) => {
cb(new Error('[404] Not found'));
}You can see the full list of supported status codes in the API Gateway section of the docs. A big thank you goes out to Stacey Moore (@staceymoore) who compiled the default error code templates.
Support for bigger CloudFormation templates
See #1740 and #1886 Serverless uses CloudFormation behind the scenes to create the necessary AWS resources for your service. When we started the work on v1 we simply used an inline string representation of the CloudFormation template to deploy it via the AWS SDK. This introduces one problem. The more complex your service gets, the bigger the template which also means that you’ll soon hit the maximum character size the AWS SDK supports for inline CloudFormation templates. We’ve updated the whole deployment process so that the CloudFormation template gets deployed alongside your zipped service to the deployment S3 bucket. This way Serverless will now support very complex services as you won’t hit the maximum size for your CloudFormation template anytime soon. Thanks Arnaud Rebts (@kid) for reporting this problem!
Documentation fixes
See #1875, #1897, #1903, #1592, #1904, #1915, #1893, #1919, #1922, #1929, #1932, #1928, #1947, #1923 An error free documentation is vital for any open source project. We’ve updated the docs and pushed some fixes and improvements there. A big thank you goes out to Erik Erikson (@erikerikson), Sean madden (@seanmadden), Cris Favero (@marioatlp), Osama Khan (@osamakhn), Kenneth Falck (@kennu) who helped to improve the documentation!
New issue and pull request templates
See #1972 Contributing to Serverless should be as easy and fun as possible. We’ve revamped the issue and pull request templates to make it even easier and more structured for you to contribute code or discuss about issues.
Rename custom authorizer default header
See #1983, #1943 and #1985 This bugfix resolves an issue where the default header was named Auth instead of Authorization by mistake. Thank you Nicko Guyer(@nguyer) and Kenneth Falck (@kennu) for reporting and Kenneth Falck (@kennu) providing a fix for this one.
Fix bug where custom CORS headers were not set
See #1984, #1988 and #1989 A bug slipped through where custom CORS headers were not set correctly. Yonah Forst (@yonahforst) and @puug were kind enough to resolve this one! Thank you!
Move from jszip to archiverjs for service zipping
See #1954, #1959 and #1961 The more packages you use, the more files need to be zipped up so that the code of your service can be uploaded to S3. We’ve used the awesome JSZip library in the past to do the archiving. Unfortunately a high amount of files to zip slows down the performance and yields to a high memory footprint which slows down deployments or even crashes CI / CD systems. From now on Serverless uses the neat Archiverjs library behind the scenes to zip your services! A big thank you goes out to Jamie Sutherland (@wedgybo) and Joseph Finlayson (@josephfinlayson) for reporting this issue and Jamie Sutherland (@wedgybo) for providing a fix. Furthermore, we’d like to thank Chris Talkington (@ctalkington) who was kind enough to release a new Archiverjs version with a necessary fix by Jamie Sutherland (@wedgybo) to resolve this issue
Allow ARN for IAM Role
See #351, #1772, #1969 and #1975 Custom ARNs which point to an IAM role can now be used as the execution role for lambda functions. Thank you to @visualasparagus and @parthaMyndbee for reporting and Takahiro Horike (@horike37) for implementing this feature.
Documentation on how to use VPCs
See #1893 Setting up and configuring a VPC is key for security when dealing with a Serverless architecture. This feature was implemented in the past, but it was not fully documented on how to use it. Erik Erikson (@erikerikson) helped here and provided the correct documentation on how to set it up.
Creating authorizers with object notation
See #1948 and #1970 A bug which prevented the correct setup of authorizers when configuring them with the help of the object notation was fixed thanks to Nicko Guyer (@nguyer) and Thomas Eschemann (@tomesch).
Removal of automatic servicePath detection (BREAKING CHANGE)
See #1192 and #1882 Until now Serverless was able to automatically detect the service even if your CWD is a deeply nested directory in your service. The previously implemented method would go back one directory at a time and check if there’s a serverless.yaml or serverless.yml file. While this was a great UX (as you don’t have to cd into the services root to execute CLI commands) it also introduces a huge potential for bugs where e.g. a command might be executed in a wrong service. We’ve removed this automatic servicePath detection so that your CWD needs to be the root of your service (where your serverless.yml file lives). This makes the whole process way more predictable and stable while moving forward.
Update of dev dependencies
See #1854 and #1879 We use different development packages like linters and their corresponding style guides (Airbnb style) to make the work on the project easier for everyone contributing code. New linting rules get introduced from time to time which means that we have to take care of updating them in time. Thankfully Ron Waldon (@jokeyrhyme) noticed this and Nick Chisiu (@nickchisiu) was kind enough to jump on this one.
Fix zipping problems on Windows machine
See #1860, #1925, #1835, #1857 and #1863 Our zipping functionality had a bug when zipping files on windows machines. This introduced strange behavior when e.g. referencing packages from the node_modules directory. Fortunately this bug has been fixed! Thanks to Adam (@smuffff) and Charlie Mills (@charliem) for reporting and Vasiliy Solovey (@miltador) and @bfhobbes for fixing this bug!
Updated artifact deployment process (BREAKING CHANGE)
See #1898, #1892, #1862 and #1906 The past deployment process only uploaded the .zipped service file to the S3 bucket. We’ve updated it so that a timestamped “directory” gets created in S3 where we’ll upload all the necessary deployment artifacts (such as the .zipped service file and the corresponding CloudFormation template). The 5 most recent versions of your deployments are stored there. If you’re updating from an older Serverless version you might want to take a look at your deployment bucket and remove old, timestamped service .zip files by hand as they’re not used anymore. Thanks to @kaklakariada who helped here by reporting issues with Java deployment.
Custom validation rules for plugin options
See #1271 and #1978 Our plugin system is the core of the framework. Nearly everything is a plugin which simply extends the Serverless core system. Plugin authors are also able to extend Serverless with the help of their own plugins. Sometimes you as a plugin author want to validate the input a user provides. In the past you could used the required: true definition to raise an error if an option was not given. While this covers some use cases it would be even more powerful if there’s a way to validate input against a regular expression and raise a custom error message when the match fails. This is now possible thanks to the work of Takahiro Horike (@horike37). Here’s an example of what a custom validation inside of a plugins options definition looks like:
options: {
stage: {
usage: 'Stage of the service',
shortcut: 's',
},
region: {
usage: 'Region of the service',
shortcut: 'r',
customValidation: {
regularExpression: /^[0-9]+$/,
errorMessage: 'Custom Error Message',
},
},
}Specifying API Gateway request passthrough behavior
See #1168 and #2000 Sometimes you need more control over how a request should be handled if an incoming content type is not setup to be handled in API Gateway. AWS has added the so called “passthrough behavior” you can use to handle such scenarios. You can use the following rules to setup whether the request should be passed through:
- NEVER
- WHEN_NO_MATCH
- WHEN_NO_TEMPLATES
This feature was implemented in a way that it defaults to NEVER so that your APIs are always secured. However you can switch to the other configuration by using the passThrough parameter in the requests http event definition:
functions:
create:
handler: posts.create
events:
- http:
method: get
path: whatever
request:
passThrough: WHEN_NO_TEMPLATESThank you Frank Schmid (@HyperBrain) for raising this issue and John DeVerna (@anreved) for implementing it!
Breaking changes
Moving fast unfortunately means that something might be reconsidered and introduces some breaking changes (which we’re sorry about).
- Renaming of resources logical IDs
- New Serverless variable system
- Removal of automatic servicePath detection
- Updated artifact deployment process
Reaching 10,000 GitHub stars
After looking at all the amazing new features it’s time to celebrate! On Friday, 19th of August Serverless finally broke the 10,000 GitHub stars mark! 
We’d like to thank everyone who has supported us so far! We’re proud to have such a great community and are excited about the future with all of you! Thank you!
New homepage
We also took some time to work on our brand new Serverless homepage. Check it out at https://serverless.com. Curious what this looks like in code? We’ve got you covered! Our homepage is open source and the corresponding code can be found here.
Your feedback / contributing to Serverless
As already mentioned in the beginning of this post, we’d like to thank each and every one of you who worked with us together to make the first release candidate of Serverless v1 so feature rich! We’re always open to feedback, issues, pull requests and anything else to help build the greatest Serverless experience you can get! Do you want to contribute to the Serverless framework? Take a look at our repository and the corresponding issue labels (milestone-discussion, discussion, help-wanted-easy and help-wanted) to get started. Also feel free to jump right into discussions on GitHub, our Serverless forum, Gitter and Twitter.
What’s next
This is our first v1 release candidate which means that Serverless v1 is right around the corner! Next up we’re planning to resolve the last issues / bugs to blaze the way for the release of Serverless v1. You can follow the progress on our v1 milestone on GitHub.
