{"id":14911,"library":"serverless-build-client","title":"Serverless Build Client Plugin","description":"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.","status":"maintenance","version":"2.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/tgfischer/serverless-build-client","tags":["javascript","serverless","framework","plugin","build","client","frontend","environment","variables"],"install":[{"cmd":"npm install serverless-build-client","lang":"bash","label":"npm"},{"cmd":"yarn add serverless-build-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add serverless-build-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is a Serverless Framework plugin and is loaded via the `plugins` array in `serverless.yml`, not through JavaScript/TypeScript module imports.","wrong":"import { ClientBuildPlugin } from 'serverless-build-client';","symbol":"serverless-build-client (plugin inclusion)","correct":"plugins:\n  - serverless-build-client"},{"note":"The plugin extends the Serverless CLI with the `client build` command; it is executed through the main `serverless` executable.","wrong":"node_modules/.bin/serverless-build-client client build","symbol":"serverless client build (CLI command)","correct":"serverless client build"},{"note":"Plugin-specific options are configured under the `custom.buildClient` object in `serverless.yml`, not directly within the plugin array entry.","wrong":"plugins:\n  - serverless-build-client: { packager: npm }","symbol":"custom.buildClient (configuration)","correct":"custom:\n  buildClient:\n    packager: npm\n    command: run build"}],"quickstart":{"code":"/* serverless.yml */\nservice: my-frontend-app\n\nplugins:\n  - serverless-build-client\n\nprovider:\n  name: aws\n  runtime: nodejs18.x\n  environment:\n    # Global environment variables for the provider\n    REACT_APP_GLOBAL_API_URL: https://api.example.com/global\n\ncustom:\n  buildClient:\n    packager: npm # Specify 'npm' as the package manager\n    command: run build # Use 'npm run build' as the build command\n    cwd: frontend # Specify the subdirectory where the client is located\n    verbose: true # Log environment variables during the build\n    environment:\n      # Plugin-specific environment variables (override global if conflict)\n      REACT_APP_BACKEND_ENDPOINT: ${cf:my-backend-service-${sls:stage}.ServiceEndpoint}\n\n# frontend/package.json (example)\n// {\n//   \"name\": \"my-client-app\",\n//   \"version\": \"1.0.0\",\n//   \"scripts\": {\n//     \"start\": \"react-scripts start\",\n//     \"build\": \"react-scripts build\"\n//   },\n//   \"dependencies\": {\n//     \"react\": \"^18.2.0\",\n//     \"react-dom\": \"^18.2.0\"\n//   }\n// }\n\n// frontend/src/App.js (example of consuming env vars)\n// import React from 'react';\n// function App() {\n//   return (\n//     <div>\n//       <h1>Frontend App</h1>\n//       <p>Global API URL: {process.env.REACT_APP_GLOBAL_API_URL}</p>\n//       <p>Backend Endpoint: {process.env.REACT_APP_BACKEND_ENDPOINT}</p>\n//     </div>\n//   );\n// }\n// export default App;\n\n# CLI Command to build the client (run from service root):\nserverless client build --stage dev\n\n# Example of deploying a backend service (from backend service root):\n# serverless deploy --stage dev","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Set `cwd: frontend` (or your client's directory name) in `custom.buildClient` within `serverless.yml`, or use `serverless client build --cwd frontend`.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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).","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","cause":"The `serverless-build-client` plugin has not been correctly installed or added to your `serverless.yml` plugins list.","error":"Command 'client' not found in serverless CLI"},{"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.","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.","error":"Error: Command failed: npm run build (or yarn build)"},{"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.","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.","error":"Environment variable 'REACT_APP_API_URL' is undefined in client-side code"}],"ecosystem":"npm"}