{"id":14039,"library":"spago","title":"Spago: PureScript Package Manager and Build Tool","description":"Spago is the official PureScript package manager and build tool, currently at version 1.0.4. It facilitates project initialization, dependency management using a package set model, compilation, and bundling of PureScript applications. The 1.x.x series represents a significant architectural shift, being a complete rewrite of the tool from its original Haskell codebase (versions up to 0.21.x) into PureScript itself. This rewrite aims for improved maintainability and tighter integration with the PureScript ecosystem. Spago provides a streamlined command-line interface for common PureScript development workflows, abstracting away the complexities of managing `purs` compiler invocations and project dependencies. Its release cadence typically involves patch updates for the stable 1.x series, following the major rewrite which occurred with the transition from 0.x to 1.x. A key differentiator is its reliance on curated package sets for consistent and conflict-free dependency resolution within the PureScript ecosystem.","status":"active","version":"1.0.4","language":"javascript","source_language":"en","source_url":"https://github.com/purescript/spago","tags":["javascript","purescript","spago","package sets","package manager","registry"],"install":[{"cmd":"npm install spago","lang":"bash","label":"npm"},{"cmd":"yarn add spago","lang":"bash","label":"yarn"},{"cmd":"pnpm add spago","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"The PureScript compiler is a strict prerequisite; Spago acts as an orchestrator and build tool for it.","package":"purescript","optional":false}],"imports":[{"note":"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.","wrong":"const { runCli } = require('spago')","symbol":"runCli","correct":"import { runCli } from 'spago'"},{"note":"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.","wrong":"import { runCli } from 'spago'","symbol":"runCli (CommonJS)","correct":"const { runCli } = require('spago')"},{"note":"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`.","wrong":"import spago from 'spago'","symbol":"spago CLI","correct":"import { spawnSync } from 'child_process'; spawnSync('spago', ['init'], { stdio: 'inherit' });"}],"quickstart":{"code":"import { spawnSync } from 'child_process';\nimport { mkdtempSync, rmSync, existsSync } from 'fs';\nimport { join } from 'path';\n\n// Create a temporary directory for the project\nconst tempDir = mkdtempSync('purescript-pasta-');\nconsole.log(`Created temporary directory: ${tempDir}`);\nprocess.chdir(tempDir);\n\ntry {\n  console.log('Running spago init...');\n  let result = spawnSync('spago', ['init'], { stdio: 'inherit' });\n  if (result.error || result.status !== 0) throw new Error('spago init failed');\n  console.log('spago init successful. Project files created.');\n\n  if (existsSync('src/Main.purs')) {\n      console.log('src/Main.purs exists, proceeding to build and run.');\n      console.log('Running spago run...');\n      result = spawnSync('spago', ['run'], { stdio: 'inherit' });\n      if (result.error || result.status !== 0) throw new Error('spago run failed');\n      console.log('spago run successful.');\n\n      console.log('Running spago bundle...');\n      result = spawnSync('spago', ['bundle', '--bundle-type', 'app', '--platform', 'node'], { stdio: 'inherit' });\n      if (result.error || result.status !== 0) throw new Error('spago bundle failed');\n      console.log('spago bundle successful.');\n\n      console.log('Running bundled app...');\n      result = spawnSync('node', ['.'], { stdio: 'inherit' });\n      if (result.error || result.status !== 0) throw new Error('Bundled app run failed');\n      console.log('Bundled app ran successfully.');\n  } else {\n      console.warn('src/Main.purs not found after spago init. Skipping build and run steps.');\n  }\n\n} catch (error) {\n  console.error('An error occurred:', error.message);\n  process.exit(1);\n} finally {\n  // Clean up the temporary directory\n  process.chdir(__dirname); // Change back to original directory before deleting tempDir\n  rmSync(tempDir, { recursive: true, force: true });\n  console.log(`Cleaned up temporary directory: ${tempDir}`);\n}","lang":"typescript","description":"Demonstrates how to programmatically initialize, build, and run a new PureScript project using `spago` commands executed via Node.js `child_process`."},"warnings":[{"fix":"Refer to the `spago` documentation for migration guides and update `spago.dhall` to `spago.yaml` where applicable. Consider using `spago-legacy` for maintaining older projects.","tags":["breaking change","configuration","migration"],"message":"Spago v1.0.0 and above is a complete rewrite in PureScript from its previous Haskell implementation (0.x.x versions). This introduces significant changes in configuration (`spago.yaml` vs `spago.dhall`) and underlying behavior. Projects using older versions must migrate to the new configuration format.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Install the PureScript compiler globally: `npm install -g purescript` or install via your OS's recommended method before using `spago`.","tags":["dependency","installation"],"message":"Spago requires the PureScript compiler (`purs`) to be installed separately. It acts as an orchestrator and build tool, not as a standalone compiler.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure your Node.js environment is at version 22.5.0 or newer. Use a Node.js version manager like `nvm` to switch or update your Node.js installation.","tags":["node.js","environment","compatibility"],"message":"The `spago` CLI tool, particularly versions 1.0.0 and above, requires Node.js version 22.5.0 or higher due to its `engines` declaration.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'0':129 '0.21':63 '1':40,116,132 '1.0.4':21 'abstract':94 'aim':70 'applic':38 'architectur':46 'away':95 'build':6,16 'bundl':35 'cadenc':108 'codebas':59 'command':86 'command-lin':85 'common':90 'compil':33,101 'complet':50 'complex':97 'conflict':148 'conflict-fre':147 'consist':145 'curat':141 'current':18 'depend':26,105,150 'develop':92 'differenti':136 'ecosystem':80,155 'facilit':23 'follow':119 'free':149 'haskel':58 'improv':72 'initi':25 'integr':76 'interfac':88 'invoc':102 'involv':110 'javascript':156 'key':135 'line':87 'maintain':73 'major':121 'manag':4,14,27,99,162 'model':32 'occur':124 'offici':11 'origin':57 'packag':3,13,30,142,159,161 'patch':111 'project':24,104 'provid':82 'pur':100 'purescript':2,12,37,66,79,91,154,157 'registri':163 'releas':107 'relianc':139 'repres':43 'resolut':151 'rewrit':51,69,122 'seri':42,118 'set':31,143,160 'shift':47 'signific':45 'spago':1,8,81,158 'stabl':115 'streamlin':84 'tighter':75 'tool':7,17,54 'transit':127 'typic':109 'updat':112 'use':28 'version':20,60 'within':152 'workflow':93 'x':64,117,130,133 'x.x':41","created_at":"2026-04-20T01:57:36.720572+00:00","updated_at":"2026-04-20T01:57:36.720572+00:00","problems":[{"fix":"`npm install -g spago` for global installation, or ensure your `PATH` includes `node_modules/.bin` if installed locally via `npm install spago`.","cause":"The `spago` executable is not in your system's PATH, or it was not installed globally/locally via `npm`.","error":"spago: command not found"},{"fix":"Install the PureScript compiler globally: `npm install -g purescript`.","cause":"The PureScript compiler (`purs`), which `spago` relies on, is not installed or discoverable in your environment.","error":"Error: Cannot find module 'purescript'"},{"fix":"Ensure `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.","cause":"The default `Main.purs` file in the `src/` directory is missing, or the `--main` flag points to a non-existent file for `spago run`.","error":"Error: No `Main.purs` file found to run."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"spago","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/purescript/spago","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/spago","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}}