Serverless Build Client Plugin

2.5.0 · maintenance · verified Sun Apr 19

serverless-build-client is a Serverless Framework plugin, currently at version 2.5.0. Its release cadence appears to be maintenance-driven rather than rapid feature development, with the last code commit being five years ago, and v2.5.0 itself being two years old. The plugin is designed to streamline the frontend build process within a Serverless project. Its primary function is to inject environment variables defined in `serverless.yml` (either globally at the provider level or specifically for the plugin) directly into the client-side build environment. This addresses a common challenge in serverless architectures where frontend applications often need dynamic values, such as API endpoints or resource identifiers, that are provisioned by the backend Serverless service. It integrates seamlessly with static site hosting plugins like `serverless-finch` by ensuring the frontend is built with correct environment configurations before deployment. Users define their build command and preferred package manager (npm or yarn), and the plugin handles the environment variable injection and execution of the build script in the specified working directory.

Common errors

```
Command 'client' not found in serverless CLI
```
cause The `serverless-build-client` plugin has not been correctly installed or added to your `serverless.yml` plugins list.

fix Ensure you have `yarn add --dev serverless-build-client` (or `npm install --save-dev serverless-build-client`) and that `- serverless-build-client` is present under the `plugins:` section in your `serverless.yml`.
```
Error: Command failed: npm run build (or yarn build)
```
cause The build command specified (default `build` for yarn, `run build` for npm) failed in the execution directory, likely due to a missing `build` script in `package.json` or other client-side build errors.

fix Verify that your client's `package.json` file in the specified `cwd` (or service root) contains a `scripts.build` entry, and that the command itself runs successfully independently. Check the full error output for details from the client build process.
```
Environment variable 'REACT_APP_API_URL' is undefined in client-side code
```
cause While the plugin injected the variable into `process.env` during the Node.js build phase, your client-side bundler is not exposing it to the browser runtime. This is a common issue with tools like Create React App or Vite if variables don't have the expected prefix.

fix Ensure your environment variables are named according to your frontend framework's conventions (e.g., `REACT_APP_` for Create React App, `VITE_` for Vite) or explicitly configured for exposure in your bundler settings.

Warnings

gotcha Environment variables configured under `custom.buildClient.environment` will override any variables with the same name defined in the `provider.environment` section. This can lead to unexpected values if not managed carefully.
Fix: Review the precedence rules for environment variables to ensure the correct values are being injected into your client build. Plugin-specific variables take precedence.
gotcha The plugin's default working directory (`cwd`) for executing the build command is the root of the Serverless service. If your client-side application's `package.json` and build scripts are in a subdirectory (e.g., `./frontend`), you *must* specify the `--cwd` CLI option or `custom.buildClient.cwd` configuration to the correct path.
Fix: Set `cwd: frontend` (or your client's directory name) in `custom.buildClient` within `serverless.yml`, or use `serverless client build --cwd frontend`.
gotcha This plugin successfully injects environment variables into the Node.js `process.env` before running your client build command. However, your frontend build tool (e.g., Create React App, Webpack, Vite) must be configured to actually *consume* these `process.env` variables and make them available in the browser-side bundle. Many tools require specific prefixes (e.g., `REACT_APP_`, `VITE_`) or explicit configuration for client-side exposure.
Fix: Consult your frontend framework/bundler documentation on how to expose Node.js `process.env` variables to the client-side code (e.g., `REACT_APP_VARIABLE_NAME` for Create React App, `VITE_VARIABLE_NAME` for Vite).

Install

npm install serverless-build-client npm
yarn add serverless-build-client yarn
pnpm add serverless-build-client pnpm

Imports

serverless-build-client (plugin inclusion)
wrong:
```
import { ClientBuildPlugin } from 'serverless-build-client';
```
correct:
```
plugins:
  - serverless-build-client
```
This package is a Serverless Framework plugin and is loaded via the `plugins` array in `serverless.yml`, not through JavaScript/TypeScript module imports.
serverless client build (CLI command)
wrong:
```
node_modules/.bin/serverless-build-client client build
```
correct:
```
serverless client build
```
The plugin extends the Serverless CLI with the `client build` command; it is executed through the main `serverless` executable.
custom.buildClient (configuration)
wrong:
```
plugins:
  - serverless-build-client: { packager: npm }
```
correct:
```
custom:
  buildClient:
    packager: npm
    command: run build
```
Plugin-specific options are configured under the `custom.buildClient` object in `serverless.yml`, not directly within the plugin array entry.

Quickstart

This example demonstrates how to configure the `serverless-build-client` plugin in `serverless.yml` to inject environment variables into a frontend application build. It shows both global provider environment variables and plugin-specific overrides, using `npm` as the packager and a custom build command from a `frontend` subdirectory. The client build then consumes these injected variables.

/* serverless.yml */
service: my-frontend-app

plugins:
  - serverless-build-client

provider:
  name: aws
  runtime: nodejs18.x
  environment:
    # Global environment variables for the provider
    REACT_APP_GLOBAL_API_URL: https://api.example.com/global

custom:
  buildClient:
    packager: npm # Specify 'npm' as the package manager
    command: run build # Use 'npm run build' as the build command
    cwd: frontend # Specify the subdirectory where the client is located
    verbose: true # Log environment variables during the build
    environment:
      # Plugin-specific environment variables (override global if conflict)
      REACT_APP_BACKEND_ENDPOINT: ${cf:my-backend-service-${sls:stage}.ServiceEndpoint}

# frontend/package.json (example)
// {
//   "name": "my-client-app",
//   "version": "1.0.0",
//   "scripts": {
//     "start": "react-scripts start",
//     "build": "react-scripts build"
//   },
//   "dependencies": {
//     "react": "^18.2.0",
//     "react-dom": "^18.2.0"
//   }
// }

// frontend/src/App.js (example of consuming env vars)
// import React from 'react';
// function App() {
//   return (
//     <div>
//       <h1>Frontend App</h1>
//       <p>Global API URL: {process.env.REACT_APP_GLOBAL_API_URL}</p>
//       <p>Backend Endpoint: {process.env.REACT_APP_BACKEND_ENDPOINT}</p>
//     </div>
//   );
// }
// export default App;

# CLI Command to build the client (run from service root):
serverless client build --stage dev

# Example of deploying a backend service (from backend service root):
# serverless deploy --stage dev

view raw JSON →