Registry / devops / primer-module-build

primer-module-build

library2.0.0jsnpmunverified

primer-module-build is a JavaScript package developed by GitHub, forming a core part of the Primer CSS ecosystem. Its primary function is to compile Primer SCSS modules into production-ready CSS, apply PostCSS transformations, and generate build statistics. Currently at version 2.0.0, the package provides both a command-line interface (CLI) for automated build processes and a programmatic API for more integrated workflows. It is essential for projects leveraging Primer CSS, offering a streamlined approach to asset compilation and optimization. While no explicit release cadence is published, it aligns with the broader Primer CSS development. Its key differentiator lies in its specialized design for the Primer framework, ensuring compatibility and leveraging internal conventions for efficient styling pipelines.

devops

npm install primer-module-build

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PRIMER-MODULE-BUIL

primer-module-build

devopsjavascriptv2.0.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.

build

✓ import { build } from 'primer-module-build';

✗ const build = require('primer-module-build').build;

The 'build' function is the primary programmatic entry point for compiling SCSS modules. While CommonJS 'require' works, ESM 'import' is recommended for modern Node.js projects.

watch

✓ import { watch } from 'primer-module-build';

✗ const watch = require('primer-module-build').watch;

The 'watch' function provides live recompilation during development, monitoring changes in SCSS files. ESM 'import' is preferred.

cli

✓ // Used via command line: primer-module-build <file.scss>

✗ import { cli } from 'primer-module-build';

The main usage is via CLI (command-line interface), not direct import of a 'cli' function. The package exports functions 'build' and 'watch' for programmatic use, but the core 'primer-module-build' command is typically invoked directly or via npm scripts.

Demonstrates both programmatic usage of the 'build' function to compile an SCSS file and mentions its CLI equivalent. This showcases a typical build flow, including path resolution and error handling.

import { build } from 'primer-module-build'; import path from 'path'; import { fileURLToPath } from 'url'; // In a real project, replace 'your-module.scss' with the actual path. // This example assumes you have an SCSS file to compile. const __filename = fileURLToPath(import.meta.url); const __dirname = path.dirname(__filename); const scssFilePath = path.join(__dirname, 'test-module.scss'); // Assuming test-module.scss exists const outputDir = path.join(__dirname, 'build'); // Example SCSS content for test-module.scss // $color: #f00; // .test-class { // color: $color; // .nested { // font-weight: bold; // } // } async function runBuild() { try { console.log(`Building SCSS from ${scssFilePath}...`); await build(scssFilePath, { outputPath: outputDir, // Other options like 'sourceMap' can be passed here }); console.log(`Build complete. CSS and stats generated in ${outputDir}/`); console.log('You can also run this from the command line:'); console.log(`npx primer-module-build ${scssFilePath}`); } catch (error) { console.error('Build failed:', error); process.exit(1); } } runBuild();

primer-module-build --version

Debug

Known issues

gotchaThe `engines.node` field in `package.json` specifies `>=4`, which is a very old and unsupported Node.js version. While the package might still function on newer Node.js runtimes, `node-sass` (a key dependency) is known to have compatibility issues with different Node.js versions, often requiring specific `node-gyp` rebuilds or precompiled binaries. Always test with your target Node.js version.

fix

Ensure your Node.js environment is compatible with `node-sass` or consider using `sass` (Dart Sass) if migrating away from `node-sass` is feasible for your project. If you encounter issues, try `npm rebuild node-sass` or `yarn rebuild node-sass`.

affects: >=2.0.0

gotchaThis package is tightly integrated with the Primer CSS ecosystem. While its build scripts are generic for SCSS and PostCSS, its configuration expectations (e.g., `primer.json`) and specific PostCSS plugins are tailored for Primer's modular architecture. Using it outside of a Primer context might require significant configuration adjustments.

fix

Review the package's source code and configuration files (e.g., `cli.js`, `index.js`) to understand its default behavior and adapt `primer.json` and `postcss.config.js` to your project's specific needs if not within the Primer framework.

affects: >=2.0.0

gotchaRunning build scripts directly from an `npm install`-ed `primer-module-build` package is not officially supported and may lead to missing file errors because the installed package might not include all necessary source files required for the build process. It's intended to be run as a development dependency within a Primer-based project.

fix

When developing with `primer-module-build`, ensure it is used as a development dependency (`npm install --save-dev primer-module-build`) within the root of your project, and that the necessary SCSS source files and configurations are accessible relative to where the build command is executed. Do not try to run its internal build scripts from within `node_modules`.

affects: >=2.0.0

Errors

Common errors & fixes

Error: `node-sass` failed to build

Often occurs when the installed `node-sass` version is incompatible with the current Node.js runtime, especially after Node.js version upgrades. Binaries compiled for one Node.js ABI version may not work with another.

fix

Delete `node_modules` and `package-lock.json` (or `yarn.lock`), then run `npm install` (or `yarn install`) to re-download and recompile `node-sass` for your current Node.js version. If that fails, try `npm rebuild node-sass` directly.

Error: Cannot find module 'postcss'

A required PostCSS dependency is missing or incorrectly resolved within the project's `node_modules` structure.

fix

Ensure `postcss` is correctly listed in `dependencies` or `devDependencies` in your `package.json` and run `npm install` (or `yarn install`) to install it. Verify that the module is present in `node_modules`.

Error: Configuration file 'primer.json' not found

The `primer-module-build` script expects a `primer.json` configuration file in a discoverable location, but it could not find it.

fix

Create a `primer.json` file in your project root or in a path where `find-up` can locate it. Refer to the `primer-module-build` documentation or source for the expected structure of this configuration file. Alternatively, ensure you are passing the correct options if using the programmatic API.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

node-sassrequiredCompiles SCSS into CSS, a core function of the build process.

postcssrequiredApplies various CSS transformations and optimizations after Sass compilation.

clean-cssrequiredMinifies the compiled CSS for production environments.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/primer/primer-module-build ↗

packagehttps://www.npmjs.com/package/primer-module-build ↗

homepagehttp://primercss.io/ ↗