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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
runCli
✓ import { runCli } from 'spago'
✗ const { runCli } = require('spago')
This is the internal programmatic entry point exposed by the package's `main` field (for ESM). Spago is primarily a CLI tool; direct programmatic imports are not the usual workflow for end-users.
runCli (CommonJS)
✓ const { runCli } = require('spago')
✗ import { runCli } from 'spago'
CommonJS equivalent for accessing the internal `runCli` function. As with ESM, this is not the primary way Spago is intended to be used by developers.
spago CLI
✓ import { spawnSync } from 'child_process'; spawnSync('spago', ['init'], { stdio: 'inherit' });
✗ import spago from 'spago'
Spago is primarily a command-line interface (CLI) tool. Programmatic interaction in Node.js environments typically involves executing `spago` as a child process, rather than importing it as a library. Ensure `spago` is accessible in your system's PATH or `node_modules/.bin`.
Demonstrates how to programmatically initialize, build, and run a new PureScript project using `spago` commands executed via Node.js `child_process`.
import { spawnSync } from 'child_process';
import { mkdtempSync, rmSync, existsSync } from 'fs';
import { join } from 'path';
// Create a temporary directory for the project
const tempDir = mkdtempSync('purescript-pasta-');
console.log(`Created temporary directory: ${tempDir}`);
process.chdir(tempDir);
try {
console.log('Running spago init...');
let result = spawnSync('spago', ['init'], { stdio: 'inherit' });
if (result.error || result.status !== 0) throw new Error('spago init failed');
console.log('spago init successful. Project files created.');
if (existsSync('src/Main.purs')) {
console.log('src/Main.purs exists, proceeding to build and run.');
console.log('Running spago run...');
result = spawnSync('spago', ['run'], { stdio: 'inherit' });
if (result.error || result.status !== 0) throw new Error('spago run failed');
console.log('spago run successful.');
console.log('Running spago bundle...');
result = spawnSync('spago', ['bundle', '--bundle-type', 'app', '--platform', 'node'], { stdio: 'inherit' });
if (result.error || result.status !== 0) throw new Error('spago bundle failed');
console.log('spago bundle successful.');
console.log('Running bundled app...');
result = spawnSync('node', ['.'], { stdio: 'inherit' });
if (result.error || result.status !== 0) throw new Error('Bundled app run failed');
console.log('Bundled app ran successfully.');
} else {
console.warn('src/Main.purs not found after spago init. Skipping build and run steps.');
}
} catch (error) {
console.error('An error occurred:', error.message);
process.exit(1);
} finally {
// Clean up the temporary directory
process.chdir(__dirname); // Change back to original directory before deleting tempDir
rmSync(tempDir, { recursive: true, force: true });
console.log(`Cleaned up temporary directory: ${tempDir}`);
}
spago --version
Errors
Common errors & fixes
spago: command not found
The `spago` executable is not in your system's PATH, or it was not installed globally/locally via `npm`.
fix`npm install -g spago` for global installation, or ensure your `PATH` includes `node_modules/.bin` if installed locally via `npm install spago`.
Error: Cannot find module 'purescript'
The PureScript compiler (`purs`), which `spago` relies on, is not installed or discoverable in your environment.
fixInstall the PureScript compiler globally: `npm install -g purescript`.
Error: No `Main.purs` file found to run.
The default `Main.purs` file in the `src/` directory is missing, or the `--main` flag points to a non-existent file for `spago run`.
fixEnsure `src/Main.purs` exists in your project, or specify the correct entry point using `spago run --main MyModule.MyMain` if your main module is elsewhere.
Audit
Dependencies
purescriptrequiredThe PureScript compiler is a strict prerequisite; Spago acts as an orchestrator and build tool for it.