@kitchenshelf/serverless-rspack NPM

⚡ serverless-rspack

Serverless Framework plugin for zero-config JavaScript and TypeScript code bundling using the high performance Rust-based JavaScript bundler rspack

Look for the plugin under the /libs directory.

Example serverless projects are under the /examples directory.

For Developers - DEVELOPER.MD

Features

From zero to hero: configuration possibilities range from zero-config to fully customizable
Supports sls package, sls deploy
Build and runtime performance at its core

Install

# install `serverless-rspack`
yarn add --dev @kitchenshelf/serverless-rspack
# or
npm install -D @kitchenshelf/serverless-rspack
# or
pnpm install -D @kitchenshelf/serverless-rspack

Add the following plugin to your serverless.yml:

plugins:
  - @kitchenshelf/serverless-rspack

Plugin Options

By default, no plugin options is required, but you can override the reasonable defaults via the custom.rspack section in the serverless.yml file.

custom:
  rspack:
    mode: 'production'
    esm: true

Examples

See example folder for example plugin option configuration.

Plugin Options

Option	Description	Default
`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`
`keepOutputDirectory`	Keeps the `.rspack` output folder. Useful for debugging.	`false`
`stats`	Generate packaging information that can be used to analyze module dependencies and optimize compilation speed.	`false`
`config`	rspack config options.	`undefined`
`config.path`	Relative rspack config path.	`undefined`
`config.strategy`	Strategy to use when a rspack config is provided.	`override`
`esm`	Output format will be ESM (experimental).	`false`
`mode`	Used to set the build mode of Rspack to enable the default optimization strategy (https://www.rspack.dev/config/mode).	`production`
`tsConfig`	Relative path to your tsconfig.	`undefined`
`externals`	Provides a way of excluding dependencies from the output bundles.	`undefined`
`scripts`	Array of scripts to execute after your code has been bundled by rspack.	`undefined`
`doctor`	Enable the `Rsdoctor` plugin.	`undefined`

Read-only default Rspack Options

The following rspack options are automatically set and cannot be overwritten.

Option	Notes
`entry`	Handler entries are determined by the plugin
`output.path`	The plugin needs to have full control over where bundles are output to, so it can correctly create zip artifacts

Function Options

Option	Description	Default
`rspack`	Set this property on a function definition to force the handler to be processed by the plugin	`undefined`

Supported Runtimes

This plugin will automatically process any function that has a runtime that starts with node i.e nodejs20.x

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 match the supported runtimes.

If you wish to force a function to be process set rspack: true on a function definition. This is handy when using custom provided node runtimes i.e runtime: 'provided.al2023'

⚠️ Note: this will only work if your custom runtime and function are written in JavaScript/Typescript. Make sure you know what you are doing when this option is set to true

Advanced Configuration

Config file

Rspack configuration can be defined by a config file.

custom:
  esbuild:
    config:
      path: './rspack.config.js'

// rspack.config.js
module.exports = (serverless) => {
  external: ['lodash'],
  // etc
};

Config file merge strategies

You can change how the plugin uses a provided config via the strategy option:

custom:
  esbuild:
    config:
      path: './rspack.config.js'
      strategy: combine

override: Default - Enables power users to provided their own complete Rspack configuration: rspack.config.js -> PluginReadOnlyDefaults
combine: Enables providing partial configuration. Merges all configuration together: PluginDefaults -> PluginOptions -> rspack.config.js -> PluginReadOnlyDefaults.

⚠️ Note: Pay attention to the order in which configuration is combined. Each time the right take precedence.

External Dependencies

By providing a regex you can mark packages as external and they will be excluded from the output bundles.

custom:
  rspack:
    externals:
      - "^@aws-sdk\/.*$"
      - "^@smithy\/.*$"
      - '^isin-validator$'

Scripts

Run custom shell commands after your code has been bundled by rspack.

Order: bundle -> scripts -> package

Scripts are executed from the root of the service directory. This is useful for modifying the output of the build before it is packaged.

Usage

custom:
  rspack:
    externals: ['^@aws-sdk/.*$', '^sharp$'],
    scripts:
      - 'echo "First script"'
      - 'cd $KS_BUILD_OUTPUT_FOLDER/App1 && npx npm init -y && npm pkg delete main && npm install --force --os=linux --cpu=x64 --include=optional sharp @img/sharp-linux-x64'
      - 'echo "Last script"'

⚠️ Note: Scripts run sequentially and will fail the build if any errors occur in any of the scripts.

Environment Variables

The following environment variables are available to your scripts:

process.env: All system environment variables.
KS_SERVICE_DIR: The absolute path to the service directory (e.g. /Users/user/code/my-service).
KS_BUILD_OUTPUT_FOLDER: The name of the build output folder (e.g. .rspack).
KS_PACKAGE_OUTPUT_FOLDER: The name of the package output folder (e.g. .serverless).

Doctor

Rsdoctor is a one-stop tool for diagnosing and analyzing the build process and build artifacts.

The serverless-rspack plugin will automatically enable the Rsdoctor plugin when the doctor option is provided.

custom:
  rspack:
    doctor: true

You can also provide an outputDirectory to specify where the report should be saved. By default, the report will be saved in the .rspack folder.

custom:
  rspack:
    doctor:
      doctor: true
      outputDirectory: ./doctor-report

⚠️ Note: Rsdoctor is configured to run in brief mode. If you want to use another mode, you can register RsdoctorRspackPlugin manually using the rspack config option.