Registry / devops / serverless-build-client

serverless-build-client

library2.5.0jsnpmunverified

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.

devops aws

npm install serverless-build-client

github ↗package ↗

INSTALL

IMPORT

SIG · SERVERLESS-BUILD-C

serverless-build-client

devopsjavascriptv2.5.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

serverless-build-client (plugin inclusion)

✓ plugins: - serverless-build-client

✗ import { ClientBuildPlugin } from '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)

✓ serverless client build

✗ node_modules/.bin/serverless-build-client client build

The plugin extends the Serverless CLI with the `client build` command; it is executed through the main `serverless` executable.

custom.buildClient (configuration)

✓ custom: buildClient: packager: npm command: run build

✗ plugins: - serverless-build-client: { packager: npm }

Plugin-specific options are configured under the `custom.buildClient` object in `serverless.yml`, not directly within the plugin array entry.

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

Debug

Known issues

gotchaEnvironment 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.

affects: >=2.0.0

gotchaThe 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`.

affects: >=2.0.0

gotchaThis 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).

affects: >=2.0.0

Errors

Common errors & fixes

Command 'client' not found in serverless CLI

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)

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

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.

Upgrade

Version history

2.5.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/tgfischer/serverless-build-client ↗

packagehttps://www.npmjs.com/package/serverless-build-client ↗