# πŸ’¨ serverless-swc [Serverless Framework](https://www.amazon.com/gp/search?ie=UTF8&tag=floydspace-20&linkCode=ur2&linkId=3c35aeea87e6a2d913a5f2110d6a2620&camp=1789&creative=9325&index=books&keywords=Serverless%20Framework) plugin for zero-config JavaScript and TypeScript code bundling using promising fast & furious [`swc`](https://github.com/evanw/swc) bundler and minifier [![serverless](http://public.serverless.com/badges/v3.svg)](https://www.serverless.com/plugins/serverless-swc) [![npm version](https://img.shields.io/npm/v/serverless-swc?color=brightgreen&label=npm%20package)](https://www.npmjs.com/package/serverless-swc) [![npm downloads](https://img.shields.io/npm/dm/serverless-swc)](https://www.npmjs.com/package/serverless-swc) [![build status](https://img.shields.io/github/actions/workflow/status/floydspace/serverless-swc/release.yml?branch=master)](https://github.com/floydspace/serverless-swc/actions) [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release) ## Features - Zero-config: Works out of the box without the need to install any additional plugins - Works with Typescript and Javascript projects - Guaranteed to work in Node.js v18 and higher environments - Supports `sls package`, `sls deploy`, `sls deploy function` - Integrates with [`Serverless Invoke Local`](https://www.serverless.com/framework/docs/providers/aws/cli-reference/invoke-local) & [`serverless-offline`](https://github.com/dherault/serverless-offline) ## Table of Contents - [Install](#install) - [Configuration](#configuration) - [Examples](#examples) - [Options](#options) - [Default Swc Options](#default-swc-options) - [Packager Options](#packager-options) - [Watch Options](#watch-options) - [Supported Runtimes](#supported-runtimes) - [Advanced Configuration](#advanced-configuration) - [Including Extra Files](#including-extra-files) - [External Dependencies](#external-dependencies) - [Swc Plugins](#swc-plugins) - [Usage](#usage) - [Automatic Compilation](#automatic-compilation) - [Serverless Offline](#serverless-offline) - [Serverless Dynamodb Local](#serverless-dynamodb-local) - [Invoke Local](#invoke-local) - [External Tools](#external-tools) - [Contributors](#contributors) ## Install ```sh # install `serverless-swc` and `swc` yarn add --dev serverless-swc swc # or npm install -D serverless-swc swc # or pnpm install -D serverless-swc swc ``` Add the following plugin to your `serverless.yml`: ```yaml plugins: - serverless-swc ``` ## Configuration By default, no configuration is required, but you can override the default behavior via the `custom.swc` section in the `serverless.yml` file. ```yml custom: swc: bundle: true minify: false ``` ### Examples See [example folder](examples) for some example configurations. ### Options | Option | Description | Default | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------- | | Swc Options | This plugin can take almost any [Swc Javascript Build Option](https://swc.github.io/api/#build-api). | [Default Swc Options](#default-swc-options) | | `concurrency` | The number of concurrent bundle operations to run at once. eg. `8`. _NOTE_: This can be memory intensive and could produce slower builds. | `Infinity` | | `zipConcurrency` | The number of concurrent zip operations to run at once. eg. `8`. _NOTE_: This can be memory intensive and could produce slower builds. | `Infinity` | | `exclude` | An array of dependencies to exclude from the Lambda. This is passed to the swc `external` option. Set to `*` to disable packaging `node_modules` | `['aws-sdk']` | | `installExtraArgs` | Optional arguments passed to npm or yarn for `external` dependency resolution. eg. `['--legacy-peer-deps']` for npm v7+ to use legacy `peerDependency` resolution behavior | `[]` | | `keepOutputDirectory` | Keeps the `.swc` output folder. Useful for debugging. | `false` | | `nativeZip` | Uses the system's `zip` executable to create archives. _NOTE_: This will produce non-deterministic archives which causes a Serverless deployment update on every deploy. | `false` | | `outputBuildFolder` | The output folder for Swc builds within the work folder. You will also need to manually override the watch ignore config if used. | `'.build'` | | `outputWorkFolder` | The output folder for this plugin where all the bundle preparation is done. You will also need to manually override the watch ignore config if used. | `'.swc'` | | `outputFileExtension` | The file extension used for the bundled output file. This will override the swc `outExtension` option | `'.js'` | | `packagePath` | Path to the `package.json` file for `external` dependency resolution. | `'./package.json'` | | `packager` | Packager to use for `external` dependency resolution. Values: `npm`, `yarn`, `pnpm` | `'npm'` | | `packagerOptions` | Extra options for packagers for `external` dependency resolution. | [Packager Options](#packager-options) | | `watch` | Watch options for `serverless-offline`. | [Watch Options](#watch-options) | | `skipBuild` | Avoid rebuilding lambda artifacts in favor of reusing previous build artifacts. | `false` | | `skipBuildExcludeFns` | An array of lambda names that will always be rebuilt if `skipBuild` is set to `true` and bundling individually. This is helpful for dynamically generated functions like serverless-plugin-warmup. | `[]` | | `stripEntryResolveExtensions` | A boolean that determines if entrypoints using custom file extensions provided in the `resolveExtensions` Swc setting should be stripped of their custom extension upon packing the final bundle for that file. Example: `myLambda.custom.ts` would result in `myLambda.js` instead of `myLambda.custom.js`. | #### Default Swc Options The following `swc` options are automatically set. | Option | Default | Notes | | ------------- | ---------- | ---------------------------------------------------------------------- | | `bundle` | `true` | Swc requires this for use with `external` | | `entryPoints` | N/A | Cannot be overridden | | `outDir` | N/A | Cannot be overridden | | `platform` | `'node'` | Set `format` to `esm` to enable ESM support | | `target` | `'node18'` | We dynamically set this. See [Supported Runtimes](#supported-runtimes) | | `watch` | N/A | Cannot be overridden | #### Packager Options | Option | Description | Default | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `scripts` | A string or array of scripts to be executed, currently only supports 'scripts' for npm, pnpm and yarn | `undefined` | | `noInstall` | [Yarn only] A boolean that deactivates the install step | `false` | | `ignoreLockfile` | [Yarn, npm only] A boolean to bypass lockfile validation, typically paired with `external` dependencies because we generate a new package.json with only the externalized dependencies. | `false` | #### Watch Options | Option | Description | Default | | ---------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | `pattern` | An [anymatch-compatible definition](https://github.com/es128/anymatch) for the watcher to respond to | `./**/*.(js\|ts)` (watches all `.js` and `.ts` files) | | `ignore` | An [anymatch-compatible definition](https://github.com/es128/anymatch) for the watcher to ignore | `['.swc', 'dist', 'node_modules', '.build']` | | `chokidar` | Any [Chokidar option](https://github.com/paulmillr/chokidar#api) | `{ ignoreInitial: true }` | #### Function Options | Option | Description | Default | | --------- | ---------------------------------------------------------------- | ----------- | | `skipSwc` | Set this property to `true` on a function definition to skip swc | `undefined` | ## Supported Runtimes This plugin will automatically set the swc `target` for the following supported Serverless runtimes: ### AWS | Runtime | Target | | ------------ | -------- | | `nodejs22.x` | `node22` | | `nodejs20.x` | `node20` | | `nodejs18.x` | `node18` | | `nodejs16.x` | `node16` | | `nodejs14.x` | `node14` | | `nodejs12.x` | `node12` | ### Google This plugin is compatible with the [serverless-google-cloudfunctions](https://github.com/serverless/serverless-google-cloudfunctions) plugin, and will set the runtimes accordingly. | Runtime | Target | | ---------- | -------- | | `nodejs24` | `node24` | | `nodejs22` | `node22` | | `nodejs20` | `node20` | | `nodejs18` | `node18` | | `nodejs16` | `node16` | | `nodejs14` | `node14` | | `nodejs12` | `node12` | ### Azure This plugin is compatible with the [serverless-azure-functions](https://github.com/serverless/serverless-azure-functions) plugin, and will set the runtimes accordingly. | Runtime | Target | | ---------- | -------- | | `nodejs18` | `node18` | | `nodejs16` | `node16` | | `nodejs14` | `node14` | | `nodejs12` | `node12` | **Please Note** When using this package in conjunction with the `serverless-azure-functions` plugin, the following additional configuration is required to ensure function apps are built correctly: ```yml package: patterns: ["host.json", "**/function.json"], ``` ### Non-Node functions If you wish to use this plugin alongside non Node functions like Python or functions with images, this plugin will automatically ignore any function which does not contain a handler or use a supported Node.js runtime. _Note:_ If you are using Python functions with Serverless Offline you will need to change the `outputWorkFolder` and `outputBuildFolder` to folder names without fullstops. ## Advanced Configuration ### Config file Swc configuration can be defined by a config file. ```yml custom: swc: config: './swc.config.js' ``` ```js // swc.config.js module.exports = (serverless) => ({ external: ['lodash'], plugins: [], }); ``` ### Including Extra Files [Serverless Package Configuration](https://www.serverless.com/framework/docs/providers/aws/guide/packaging#package-configuration) will behave in the same way as native packaging. You can use `patterns`, `include` and `exclude` to include extra files into your bundles. ### External Dependencies Packages that are marked as `external` and exist in the package.json's `dependencies` will be installed and included with your build under `node_modules`. You can customize this with a number of options. ```yml custom: swc: external: - lodash packager: yarn packagePath: absolute/path/to/package.json packagerOptions: scripts: - echo 'Hello World!' - rm -rf node_modules installExtraArgs: - '--legacy-peer-deps' ``` To easily mark all the `dependencies` in `package.json` as `external`, you can utilize `swc-node-externals` [plugin](https://www.npmjs.com/package/swc-node-externals). To mark one or more individual packages as external, use the following configuration: ```yml custom: swc: external: - 'my-package-name' - 'another-package-name' ``` ### Swc Plugins _Note: The [Swc plugins API](https://swc.github.io/plugins/) is still experimental_ You can configure swc plugins by passing a plugins' configuration file: ```yml custom: swc: plugins: plugins.js ``` The plugins' configuration file must be a javascript file exporting an array of plugins (see `examples/individually/plugins.js` for a dummy plugin example): ```javascript let myPlugin = { name: 'my-plugin', setup(build) { // plugin implementation }, }; // default export should be an array of plugins module.exports = [myPlugin]; ``` or a function that accepts `serverless` instance and returns an array of plugins (see [issue #168](https://github.com/floydspace/serverless-swc/issues/168) for an example): ```javascript module.exports = (serverless) => { const myPlugin = { name: 'my-plugin', setup(build) { // plugin implementation with `serverless` instance access console.log('sls custom options', serverless.service.custom); }, }; // an array of plugins must be returned return [myPlugin]; }; ``` ## Usage ### Automatic compilation As long as the plugin is properly installed, all regular Serverless operations `sls package`, `sls deploy`, `sls deploy function`, `sls invoke local`, `sls offline` will automatically compile using `serverless-swc`. ### Specify a custom entrypoint for a function You can specify a custom entrypoint for Swc by specifying the `swcEntrypoint` field in your function definition. ```typescript export const myLambdaFunction = { handler: '/opt/nodejs/node_modules/my_custom_extension/handler.handler', swcEntrypoint: './handler.main', }; ``` ### Serverless Offline The plugin integrates very well with [serverless-offline](https://github.com/dherault/serverless-offline) to simulate AWS Lambda and AWS API Gateway locally. Add the plugins to your `serverless.yml` file and make sure that `serverless-swc` precedes `serverless-offline` as the order is important: ```yaml plugins: ... - serverless-swc ... - serverless-offline ... ``` Run `serverless offline` or `serverless offline start` to start the Lambda/API simulation. 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) Automatic compilation is available while using the plugin with `serverless-offline`. ```yml custom: swc: watch: pattern: ['src/**/*.ts'] # match only typescript files in src directory ignore: ['temp/**/*'] ``` Note: When overriding the ignore pattern, remember to ignore `.build` directory to avoid endless compilation. #### Serverless Dynamodb Local Configure your service the same as mentioned above, but additionally add the `serverless-dynamodb-local` plugin as follows: ```yaml plugins: - serverless-swc - serverless-dynamodb-local - serverless-offline ``` Run `serverless offline start`. ### Invoke Local This plugin supports the Serverless [Invoke Local](https://www.serverless.com/framework/docs/providers/aws/cli-reference/invoke-local) functionality and will automatically compile the selected function. ## External Tools - [`serverless-analyze-bundle-plugin`](https://github.com/adriencaccia/serverless-analyze-bundle-plugin): a plugin that allow users to analyze the bundle of a lambda ## Contributors
Victor Korzunin
Victor Korzunin
πŸ’¬ πŸ’» πŸ“– πŸ’‘ πŸ€” πŸš‡ 🚧 πŸ”Œ πŸ“† πŸ‘€ ⚠️ πŸ”§		 Loup Topalian
Loup Topalian
πŸ’¬ πŸ’» πŸ“– πŸš‡ 🚧 πŸ”Œ		 Sam Chung
Sam Chung
πŸ’¬ πŸ’» πŸ“– πŸ’‘ πŸš‡ 🚧 πŸ”Œ πŸ‘€ πŸ”§		 Vamsi Dharmavarapu
Vamsi Dharmavarapu
πŸ’» πŸ“– πŸ’‘ πŸš‡ 🚧		 Eric
Eric
πŸ’» πŸ€” 🚧 πŸš‡ πŸ‘€		 Chris
Chris
πŸ’» πŸ€”		 MartΓ­n Acosta
MartΓ­n Acosta
πŸ’»
Tony Tyrrell
Tony Tyrrell
πŸ’»		 Matt Jennings
Matt Jennings
πŸ’»		 Misha Bruml
Misha Bruml
πŸ’»		 FranΓ§ois Farge
François Farge
πŸ’»		 Sam Hulick
Sam Hulick
πŸ“–		 Troy Ready
Troy Ready
πŸ’»		 subash adhikari
subash adhikari
πŸ’»
Dan Ionescu
Dan Ionescu
πŸ’»		 gurushida
gurushida
πŸ’»		 nickygb
nickygb
πŸ’»		 Jiri Spac
Jiri Spac
πŸ’»		 gavynriebau
gavynriebau
πŸ“–		 Adrien Cacciaguerra
Adrien Cacciaguerra
πŸ“–		 lulzneko
lulzneko
πŸ’»
AOKI Yuuto
AOKI Yuuto
πŸ’»		 Thomas Aribart
Thomas Aribart
πŸ€”		 Kory Hutchison
Kory Hutchison
πŸ’» πŸ€”		 Chris Hutchinson
Chris Hutchinson
πŸ’»		 Fredrik MΓΆllerstrand
Fredrik MΓΆllerstrand
πŸ’»		 Sander Kooger
Sander Kooger
πŸ’»		 Adam Swift
Adam Swift
πŸ’»
Florian Mayer
Florian Mayer
πŸ’»		 Zach Levi
Zach Levi
πŸ’»
Inspired by [serverless-plugin-typescript](https://github.com/prisma-labs/serverless-plugin-typescript) and [serverless-webpack](https://github.com/serverless-heaven/serverless-webpack)