{"id":13813,"library":"primer-module-build","title":"Primer Module Build","description":"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.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/primer/primer-module-build","tags":["javascript","primer","build","css","postcss","node-sass"],"install":[{"cmd":"npm install primer-module-build","lang":"bash","label":"npm"},{"cmd":"yarn add primer-module-build","lang":"bash","label":"yarn"},{"cmd":"pnpm add primer-module-build","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Compiles SCSS into CSS, a core function of the build process.","package":"node-sass"},{"reason":"Applies various CSS transformations and optimizations after Sass compilation.","package":"postcss"},{"reason":"Minifies the compiled CSS for production environments.","package":"clean-css"}],"imports":[{"note":"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.","wrong":"const build = require('primer-module-build').build;","symbol":"build","correct":"import { build } from 'primer-module-build';"},{"note":"The 'watch' function provides live recompilation during development, monitoring changes in SCSS files. ESM 'import' is preferred.","wrong":"const watch = require('primer-module-build').watch;","symbol":"watch","correct":"import { watch } from 'primer-module-build';"},{"note":"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.","wrong":"import { cli } from 'primer-module-build';","symbol":"cli","correct":"// Used via command line: primer-module-build <file.scss>"}],"quickstart":{"code":"import { build } from 'primer-module-build';\nimport path from 'path';\nimport { fileURLToPath } from 'url';\n\n// In a real project, replace 'your-module.scss' with the actual path.\n// This example assumes you have an SCSS file to compile.\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\nconst scssFilePath = path.join(__dirname, 'test-module.scss'); // Assuming test-module.scss exists\nconst outputDir = path.join(__dirname, 'build');\n\n// Example SCSS content for test-module.scss\n// $color: #f00;\n// .test-class {\n//   color: $color;\n//   .nested {\n//     font-weight: bold;\n//   }\n// }\n\nasync function runBuild() {\n  try {\n    console.log(`Building SCSS from ${scssFilePath}...`);\n    await build(scssFilePath, {\n      outputPath: outputDir,\n      // Other options like 'sourceMap' can be passed here\n    });\n    console.log(`Build complete. CSS and stats generated in ${outputDir}/`);\n    console.log('You can also run this from the command line:');\n    console.log(`npx primer-module-build ${scssFilePath}`);\n  } catch (error) {\n    console.error('Build failed:', error);\n    process.exit(1);\n  }\n}\n\nrunBuild();","lang":"javascript","description":"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."},"warnings":[{"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`.","message":"The `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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"This 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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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`.","message":"Running 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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"search_vec":"'2.0.0':48 'align':96 'api':66 'appli':38 'approach':82 'asset':84 'autom':60 'broader':99 'build':3,7,43,61,127 'cadenc':92 'cli':58 'command':55 'command-lin':54 'compat':116 'compil':29,85 'convent':120 'core':17 'css':22,37,78,101,128 'current':45 'design':110 'develop':12,102 'differenti':105 'ecosystem':23 'effici':122 'ensur':115 'essenti':73 'explicit':90 'form':15 'framework':114 'function':26 'generat':42 'github':14 'integr':69 'interfac':57 'intern':119 'javascript':10,125 'key':104 'leverag':76,118 'lie':106 'line':56 'modul':2,6,32 'node':131 'node-sass':130 'offer':79 'optim':87 'packag':11,50 'part':18 'pipelin':124 'postcss':39,129 'primari':25 'primer':1,5,21,30,77,100,113,126 'primer-module-build':4 'process':62 'product':35 'production-readi':34 'programmat':65 'project':75 'provid':51 'publish':94 'readi':36 'releas':91 'sass':132 'scss':31 'special':109 'statist':44 'streamlin':81 'style':123 'transform':40 'version':47 'workflow':70","created_at":"2026-04-20T01:56:26.710021+00:00","updated_at":"2026-04-20T01:56:26.710021+00:00","problems":[{"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.","cause":"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.","error":"Error: `node-sass` failed to build"},{"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`.","cause":"A required PostCSS dependency is missing or incorrectly resolved within the project's `node_modules` structure.","error":"Error: Cannot find module 'postcss'"},{"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.","cause":"The `primer-module-build` script expects a `primer.json` configuration file in a discoverable location, but it could not find it.","error":"Error: Configuration file 'primer.json' not found"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"primer-module-build","cli_version":null,"type":"library","homepage":"http://primercss.io/","github":"https://github.com/primer/primer-module-build","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/primer-module-build","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}