CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-serverless-webpack

Serverless Framework plugin that bundles Lambda functions with Webpack for optimized JavaScript deployment packages

—

Pending
Overview
Eval results
Files

configuration.mddocs/

Plugin Configuration

Plugin configuration system for customizing webpack behavior, module packaging, and build options through the custom.webpack section in serverless.yml.

Capabilities

Basic Configuration

Configure the plugin through the custom.webpack section in your serverless.yml file.

custom:
  webpack:
    webpackConfig: string              # Path to webpack configuration file (default: 'webpack.config.js')
    includeModules: boolean | object   # External module inclusion settings (default: false)
    packager: 'npm' | 'yarn'          # Package manager selection (default: 'npm')
    packagerOptions: object           # Package manager specific options (default: {})
    excludeFiles: string              # Glob pattern for file exclusion
    excludeRegex: string              # Regex pattern for file exclusion  
    keepOutputDirectory: boolean      # Preserve webpack output directory (default: false)
    concurrency: number               # Compilation concurrency level (default: os.cpus().length)
    config: object                    # Custom configuration object

Usage Examples:

# Basic configuration
custom:
  webpack:
    webpackConfig: './config/webpack.config.js'
    includeModules: true
    packager: 'yarn'

# Advanced configuration
custom:
  webpack:
    webpackConfig: './build/webpack.prod.js'
    includeModules:
      packagePath: '../package.json'
      nodeModulesRelativeDir: '../../'
      forceExclude:
        - 'aws-sdk'
      forceInclude:
        - 'pg'
    packager: 'npm'
    packagerOptions:
      scripts:
        - 'build:custom'
    excludeFiles: 'src/**/*.test.js'
    concurrency: 4
    keepOutputDirectory: true

Webpack Configuration File

Specify the path to your webpack configuration file.

# String format (legacy support)
custom:
  webpack: './my-webpack.config.js'

# Object format (recommended)  
custom:
  webpack:
    webpackConfig: './my-webpack.config.js'

The webpack configuration file can export:

  • Synchronous configuration object
  • Asynchronous function returning configuration
  • Promise resolving to configuration

Usage Examples:

// Basic webpack config
module.exports = {
  entry: './handler.js',
  target: 'node',
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        use: 'babel-loader'
      }
    ]
  }
};

// Async webpack config with serverless-webpack lib
const slsw = require('serverless-webpack');

module.exports = async () => {
  const accountId = await slsw.lib.serverless.providers.aws.getAccountId();
  return {
    entry: slsw.lib.entries,
    target: 'node',
    plugins: [
      new webpack.DefinePlugin({
        AWS_ACCOUNT_ID: JSON.stringify(accountId)
      })
    ]
  };
};

Module Inclusion Configuration

Configure how external modules are included in the deployment package.

# Boolean format
includeModules: boolean

# Object format for advanced configuration
includeModules:
  packagePath: string                  # Relative path to package.json (default: './package.json')
  nodeModulesRelativeDir: string      # Relative path to node_modules directory
  packageLockPath: string             # Path to package-lock.json for NPM 8+ support
  forceExclude: string[]              # Modules to force exclude from packaging
  forceInclude: string[]              # Modules to force include in packaging

Usage Examples:

# Simple inclusion
custom:
  webpack:
    includeModules: true

# Monorepo configuration
custom:
  webpack:
    includeModules:
      packagePath: '../package.json'
      nodeModulesRelativeDir: '../../'
      packageLockPath: '../../package-lock.json'

# Selective module inclusion
custom:
  webpack:
    includeModules:
      forceExclude:
        - 'aws-sdk'      # Already available in Lambda runtime
        - 'dev-only-pkg'
      forceInclude:
        - 'optional-dep'  # Include optional dependency

Packager Configuration

Configure the package manager used for installing and managing dependencies.

packager: 'npm' | 'yarn'               # Package manager selection

packagerOptions:                       # Packager-specific options
  scripts: string[]                    # Additional scripts to run after install
  noInstall: boolean                   # Skip install step
  ignoreLockfile: boolean             # Ignore lock file during install
  [customOption: string]: any         # Additional packager-specific options

Usage Examples:

# NPM configuration
custom:
  webpack:
    packager: 'npm'
    packagerOptions:
      scripts:
        - 'rebuild'
        - 'prepare:prod'

# Yarn configuration  
custom:
  webpack:
    packager: 'yarn'
    packagerOptions:
      ignoreLockfile: false
      scripts:
        - 'postinstall'

File Exclusion Configuration

Configure which files should be excluded from the webpack compilation process.

excludeFiles: string                   # Glob pattern for file exclusion
excludeRegex: string                  # Regular expression pattern for file exclusion

Usage Examples:

custom:
  webpack:
    excludeFiles: 'src/**/*.test.js'   # Exclude test files
    
# Multiple patterns
custom:
  webpack:
    excludeFiles: '{src/**/*.test.js,src/**/*.spec.js,**/*.stories.js}'

# Regex pattern
custom:
  webpack:
    excludeRegex: '\\.(test|spec)\\.(js|ts)$'

Build Output Configuration

Configure webpack output behavior and directory management.

keepOutputDirectory: boolean          # Preserve .webpack directory after build (default: false)
concurrency: number                   # Number of concurrent webpack compilations (default: os.cpus().length)

Usage Examples:

custom:
  webpack:
    keepOutputDirectory: true         # Keep .webpack directory for debugging
    concurrency: 2                    # Limit concurrent compilations
    
# Dynamic concurrency via CLI
custom:
  webpack:
    concurrency: ${opt:compile-concurrency, 4}

Legacy Configuration Support

The plugin maintains backward compatibility with legacy configuration formats.

# Legacy format (still supported)
custom:
  webpack: 'path/to/webpack.config.js'
  webpackIncludeModules: boolean

Migration Example:

# Legacy format
custom:
  webpack: './webpack.config.js'
  webpackIncludeModules: true

# Modern equivalent
custom:
  webpack:
    webpackConfig: './webpack.config.js'
    includeModules: true

Configuration Class

The plugin uses an internal Configuration class to manage settings.

/**
 * Plugin configuration management class
 */
class Configuration {
  /**
   * Create configuration from serverless.yml custom.webpack section
   * @param custom - The custom.webpack configuration object
   */
  constructor(custom: any);
  
  /** Path to webpack configuration file getter */
  webpackConfig: string;
  
  /** Module inclusion configuration getter */
  includeModules: boolean | object;
  
  /** File exclusion glob pattern getter */
  excludeFiles: string;
  
  /** File exclusion regex pattern getter */
  excludeRegex: string;
  
  /** Package manager selection getter */
  packager: string;
  
  /** Package manager options getter */
  packagerOptions: object;
  
  /** Custom configuration object getter */
  config: object;
  
  /** Legacy configuration detection getter */
  hasLegacyConfig: boolean;
  
  /** Output directory preservation flag getter */
  keepOutputDirectory: boolean;
  
  /** Compilation concurrency setting getter */
  concurrency: number;
  
  /** Serialize configuration to JSON */
  toJSON(): object;
}

Default Configuration Values

// Default configuration applied when values are not specified
const DefaultConfig = {
  webpackConfig: 'webpack.config.js',
  includeModules: false,
  packager: 'npm',
  packagerOptions: {},
  keepOutputDirectory: false,
  config: null,
  concurrency: require('os').cpus().length
};

Install with Tessl CLI

npx tessl i tessl/npm-serverless-webpack

docs

build-compilation.md

configuration.md

development-integration.md

index.md

module-packaging.md

packagers.md

utilities.md

webpack-integration.md

tile.json