Meteor Client Bundler

1.3.0 · active · verified Sun Apr 19

meteor-build-client is a command-line interface (CLI) tool designed to bundle the client-side assets of a Meteor application into a static `index.html` and associated CSS/JS files. This allows the client application to be hosted on any static web server or even loaded directly via the `file://` protocol, decoupling it from a live Meteor server for its static assets. The package is currently at version 1.3.0, with recent updates (like 1.3.0) focusing on compatibility with newer Meteor versions (e.g., `meteor@2.8.0`), bug fixes, and user experience improvements like prompt skipping. Its primary differentiator is enabling a pure client-only Meteor build without requiring the full Meteor server stack for serving the initial bundle, which is useful for CDN deployment or offline access. Release cadence appears tied to Meteor compatibility and addressing reported issues.

Common errors

```
Error: EEXIST: file already exists, open '...' (output directory)
```
cause The output directory for `meteor-build-client` already contains files, and the tool is configured to prompt before overwriting (default behavior before v1.3.0, or if `--yci` is not used).

fix Clear the output directory manually before running the command, or add the `-y` or `--yci` flag to `meteor-build-client` to automatically confirm overwrites: `meteor-build-client ../output --yci`.
```
ReferenceError: Meteor is not defined
```
cause The bundled client application is trying to connect to a Meteor server, but `ROOT_URL` is not correctly set, or the client cannot reach the server at the specified URL.

fix Ensure `meteor-build-client` is run with the `--url <ROOT_URL>` option pointing to your Meteor backend server (e.g., `meteor-build-client ../output --url https://api.yourdomain.com`). Also verify network connectivity and server availability.
```
File duplicates in generated markup
```
cause An internal issue within the bundler sometimes caused multiple entries for the same file in the generated `index.html`.

fix This was addressed in version 1.2.1. Update `meteor-build-client` to version 1.2.1 or newer: `npm update -g meteor-build-client`.

Warnings

breaking The spinner functionality and associated command-line options (`-hide`, `--hideSpinner`) were removed in version 1.0.0. The `simple-spinner` dependency was also dropped.
Fix: Remove any usage of `-hide` or `--hideSpinner` flags from your build scripts.
gotcha The content of the specified output directory will be deleted before a new build. This can lead to data loss if important files are stored there. As of v1.3.0, a prompt is shown before overwriting, unless `-y` or `--yci` flags are used.
Fix: Always specify a dedicated, empty, or expendable directory as the output target. Use the `-y` or `--yci` flags to explicitly confirm overwriting in CI/CD environments if desired.
gotcha Dynamic imports (e.g., `import('/eager/file')`) are not supported by `meteor-build-client` and will cause issues or errors in the bundled output.
Fix: Avoid using dynamic `import()` statements in your Meteor client-side code when bundling with `meteor-build-client`. Use static imports or alternative loading mechanisms.
gotcha The package defaults to linking the `legacy` ES5 bundle build. If you require a modern ES6 build, you need to ensure your Meteor project is configured accordingly and potentially use the `--usebuild` option with a specifically generated modern build.
Fix: Verify your Meteor project's build settings for modern/legacy targets. If bundling a pre-built Meteor directory, ensure that directory contains the desired build targets.

Install

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

Imports

meteor-build-client
wrong:
```
import { buildClient } from 'meteor-build-client';
```
correct:
```
npm install -g meteor-build-client
# Then use in shell: meteor-build-client <output-directory>
```
This package is a command-line interface (CLI) tool and not designed for programmatic import or `require()` usage within JavaScript/TypeScript applications. It is installed globally and run as a shell command.
CLI Options
wrong:
```
const builder = new MeteorBuildClient(); builder.build();
```
correct:
```
meteor-build-client --help
meteor-build-client ../output --settings ../settings.json
```
Interaction is solely via command-line arguments. There is no public programmatic API to instantiate or call functions from this package directly within a Node.js script beyond spawning a child process.
Output integration
wrong:
```
import 'meteor-build-client/bundle-styles.css';
```
correct:
```

<head>
  <meteor-bundled-css />
</head>
<body>
  <meteor-bundled-js />
</body>
```
The tool processes special `<meteor-bundled-css />` and `<meteor-bundled-js />` tags in your `index.html` to inject generated asset links. These are not JavaScript imports but HTML placeholders the CLI tool understands.

Quickstart

This quickstart demonstrates how to install the `meteor-build-client` CLI globally and use it to bundle a Meteor application's client-side assets into a static directory, including options for specifying a ROOT_URL, using a pre-existing Meteor build, and passing application settings, while skipping prompts.

npm install -g meteor-build-client

# Navigate to your Meteor application directory
cd /path/to/my/meteor/app

# Example 1: Build client into a new directory
meteor-build-client ../client-output --url https://my-cdn.com

# Example 2: Use a pre-built Meteor bundle (e.g., from 'meteor build --directory')
meteor build ../full-app-build --directory
meteor-build-client ../client-output-from-full --url https://my-cdn.com --usebuild ../full-app-build

# Example 3: Build with settings.json and skip overwrite prompt
meteor-build-client ../client-output --settings ./settings.json --yci

view raw JSON →