A Serverless v1 plugin that uses
browserifyto bundle your Node.js Lambda functions.
Smaller Lambda functions that run faster, with minimal changes to normal serverless configuration.
A project usualy contains several dependencies that are required by different functions in miscellaneous combinations, and packaging it all up for every function generates very large and inefficient bundles. This plugin leverages browserify's ability of bundling up all files requested using require, generating a single lean file with all that is needed for each specific function.
Normal serverless packaging includes all files within the node_modules structures, including several files that are not really needed during runtime, like package.json files, documentation files, and much more. And although recent versions of serverless automatically ignore devDependencies, you'll certainly still have more dependencies than needed for each single function.
Serverless does support manual preparation of packages, but you will still have to take care of that for each single function individually, which can quickly get out of hand dependending on the number of dependencies you need. This is specially hard after npm v3, due to dependency tree flattening.
The reduction is package size is, on average, superior to 90%. This is important as AWS Lambda has an account-wide deployment package size limit, and reduces file transfer times.
Less code to parse also means quicker Lambda cold start.
When using this plugin, one of the goals is to reduce serverless configuration changes as much as possible. It must possible to just remove it and resume normal usage of serverless, without any additional modifications.
No preset uglification, minification, nor transpilation; just plain bundling. You can add any other transformations you want by using common browserify plugins.
From your target serverless project, run:
npm install serverless-plugin-browserifier --save-dev
Add the plugin to your serverless.yml:
plugins:
- serverless-plugin-browserifier
package:
individually: trueThe package.individually setting must be set -- either on global or function level -- to allow minimal bundle size based on each lambda's entrypoint.
You're all set! Use your normal serverless commands to package and deploy.
For most use cases you should NOT need to do any extra configuration. That said, the ability is present if you need it.
The base config for browserify is read from the custom.browserify section of serverless.yml. All browserify options are supported (most are auto configured by this plugin). This plugin adds one special option disable which if true will bypass this plugin.
The base config can be overridden on a function-by-function basis. Again, custom.browserify is not required and should not even need to be defined in most cases.
custom:
browserify:
# any option defined in https://github.com/substack/node-browserify#browserifyfiles--opts
functions:
usersGet:
description: Get users
handler: users/index.handler
browserify:
noParse:
- ./someBig.json #browserify can't optimize json, will take long time to parse for nothingIf you find a package that is not supported or does not behave well with browserify, you can still use function level package.include to include extra modules and files to your package. That said, you are encouraged to verify if you specific case can be dealt with by leveraging all available browserify options in your serverless.yml custom browserify section.
You can still use serveless' package[include|exclude] options to include extra files within your bundles, if necessary.
You can disable the plugin completely by setting the global or function level disable flag:
custom:
browserify:
disable: true
# ... or ...
functions:
usersGet:
handler: users/index.handler
browserify:
disable: trueWhen this plugin is enabled, and package.individually is true, running serverless deploy and serverless deploy -f <funcName> will automatically browserify your Node.js lambda code.
If you want to see more information about the process, simply set envvar SLS_DEBUG=* for full serverless debug output, or SLS_BROWSERIFIER_DEBUG=* for plugin only debug messages. Example:
$ export SLS_DEBUG=*
$ sls deploy function -v -f usersGet
You may also verify your bundles by simply using sls package, which bundles everything up but does not deploy.
If you want to use browserify plugins, you can easily do that by using the global browserify options. As the plugin merely passes that up to browserify, as if it is calling the main browserify function, you can use it to add any transformations you want.
Do you want to transpile using TypeScript? No problem! You can use tsify:
# if you have no transform package options
custom:
browserify:
transform:
- tsify # single dash!
# if you have extra transform package options
custom:
browserify:
transform:
- - tsify # array of array, two dashes!
- noImplicitAny: true
# multiple mixed transforms
custom:
browserify:
transform:
- jstify
- - tsify
- noImplicitAny: trueFor an in-depth example, please check this issue.
The official aws-sdk-js officially supports browserify. That allows us to further reduce the size of our bundles (and Lambda memory usage and speed) by loading only what is strictly needed.
// instead of ...
const AWS = require('aws-sdk')
const s3 = new AWS.S3()
// ... you should use ...
const S3 = require('aws-sdk/clients/s3')
const s3 = new S3()Although you can use discrete clients (see item above), AWS Lambda service always bundles up the latest SDK version in its Lambda container image. That means that, even if you don't add AWS SDK to your bundle, it will still be available in runtime.
Therefore, if you don't need any specific AWS SDK version, you can add the following to your plugin config:
custom:
browserify:
exclude:
- aws-sdk
- aws-sdk/clients/s3To help you out, here's a script you can use to hide aws-sdk and all its clients from browserify. You can use it in your custom config for the plugin in serverless.yml:
# serverless.yml
custom:
browserify: browserify: ${file(./custom.browserify.js)}// custom.browserify.js
//
const fs = require('fs')
const path = require('path')
module.exports = function browserifyOptions () {
return {
// any other valid browserify configuration...
noParse: ['/**/*.json'],
exclude: ['aws-sdk', ...getAllAwsSdkClients()]
}
}
function getAllAwsSdkClients () {
return fs
.readdirSync('./node_modules/aws-sdk/clients', { withFileTypes: true })
.filter(file => file.isFile() && path.extname(file.name) === '.js')
.map(file => `aws-sdk/clients/${path.basename(file.name, '.js')}`)
}Should I use Webpack instead of this plugin?
Browserify, in general, supports more modules, optimises better (generates smaller bundles), and requires less configuration. Webpack is an amazing tool, but it comes with several extras that are not really needed within a pure Node.js environment.
What about uglification? And babel?
You should be able to use uglify-es through uglifyify. For babel usage, babelify should do the trick. Refer back to Using browserify plugins section to set it up.
Avoid mixing this plugin with other plugins that modify serverless' packaging behaviour!
This plugin hijacks the normal serverless packaging process, so it will probably conflict with other plugins that use similar mechanisms.
- List of browserify's transforms
- A curated list of awesome Browserify resources, libraries, and tools.
MIT License.
This project has been forked from the original serverless-plugin-browserify and published under a different name, as the original has been abandoned.
For the complete information, please refer to the license file.