spago.nix
offers a number of functions providing Nix integration for Spago projects. These are contained in a top-level spago-nix
namespace that can be accessed by applying its overlay (overlays.default
provided by the spago.nix
flake). This document provides an overview of the different library functions and data structures that are made available.
This is the primary interface to working with spago.nix
. It takes a src
containing a Purescript project and generates several useful flake outputs along with several functions (see below)
name
- (Required)
The project name. Used to set the names of derivations generated in
spagoProject
- Type
- string
src
- (Required)
A Nix store path pointing to the project sources
- Type
- path
shell
-
Holds configuration options for the generated
devShell
. ThedevShell
will always contain a suitable version ofpurs
andspago
- Type
- attribute set
- Default
-
{ # Purescript development tools, as made available under # `pkgs.purescriptPackages` (this is added by the overlay # from `difficult-purescript-nix`, which is automatically # applied for you when you apply `spago-nix.overlays.default`) # # This argument must be an attribute set, where each name # is mapped to either an empty attribute set (which implies # the latest version of the package), the string `"latest"`, # which implies the same, or a specific version, such as # `"0.16.6"`. Note that if you specify a version, the # `pkgs.purescriptPackages` set must contain the package with # the specified version as a suffix, e.g.: # # `pkgs.purescriptPackages.purescript-language-server-0_16_6` # # Whatever `tools` you specify here are also returned by # `spagoProject`, under the `tools` attribute tools = { }; # Corresponds to `packages` argument of `pkgs.mkShell` packages = [ ]; # If `true`, the Spago packages will be installed in `./.spago` in # the `devShell`'s `shellHook` install = true; # If `true`, `npm install` will only write to `package-lock.json` # (and never to `node_modules`) packageLockOnly = true; # Gets appended to the `shellHook` created for you in the `devShell` shellHook = ""; }
- Example
-
{ packages = { psa = { }; purs-tidy = "latest"; purescript-language-server = "0.16.6"; }; packageLockOnly = false; shellHook = '' echo 'my shell hook' ''; }
extraSources
-
A mapping from dependency names to their sources. Can be easily converted from flake
inputs
. Note: The sources provided must match the revisions in yourpackages.dhall
exactly. Otherwise hard-to-debug errors will likely arise- Type
- attribute set
- Default
-
{ }
- Example
-
{ inherit (inputs) foo bar; }
sha256map
-
A mapping from dependency names to their sha256 hashes and exact revisions. Can also be converted from flake
inputs
. Note: It is considerably more convenient and efficient to useextraSources
, as the corresponding dependencies will be fetched from the network when usingsha256map
- Type
- attribute set
- Default
-
{ }
- Example
-
{ foo = { inherit (inputs.foo) rev; sha256 = inputs.foo.narHash; }; }
flags
-
Contains various flags used for compiling the project sources and installing dependencies
- Type
- attribute set
- Default
-
{ # Turns on `--strict` during compilation; corresponds to # `psa --strict ...` strict = true; # List of warnings to silence during compilation. For example # `[ "UserDefinedWarning" ]` censorCodes = [ ]; # If set, the generated `node_modules` will also contain all # of the `devDependencies` declared in the `package.json` development = true; }
- Example
-
{ censorCodes = [ "UserDefinedWarning" ]; development = false; }
nodejs
-
The specific version of
nodejs
to use. Will be used throughout the project components and in thedevShell
- Type
- derivation
- Default
-
pkgs.nodejs-14_x
- Example
-
pkgs.nodejs-18_x
buildConfig
-
Holds paths to various build configuration files
- Type
- attribute set
- Default
-
{ packagesDhall = src + "/packages.dhall"; spagoDhall = src + "/spago.dhall"; packageJson = src + "/package.json"; packageLock = src + "/package-lock.json"; }
- Example
-
{ spagoDhall = src + "/some/weird/path/spago.dhall"; }
withDocs
-
If
true
,spagoProject
will build docs using default values for options and add them to theflake
attribute that is returned. Even if this isfalse
, you can still use thebuildDocs
builder to generate documentation- Type
- boolean
- Default
-
true
- Example
-
false
This contains utilities for working with flake apps
. As these can be applied outside of the context of spagoProject
, they are not returned from that function unlike the other functions documented below
Turn a NodeJS app (e.g. using nodeApp
) into a flake app. If you pass arguments to the nix run
invocation, these will be passed to the provided application.
Note: If you do pass command-line arguments, you should provide the command name as the first argument on the command line (Node’s proces.env.argv
always contains the command’s name as its first element). Alternately, the provided app
can be created using nodeAppWithArgs
with a command
argument and an empty list for its arguments
(the default value). For example:
pkgs.spago-nix.utils.fromNodeApp {
app = project.nodeAppWithArgs {
main = "The.Main.Module";
# or you can leave it empty, a default will be created
command = "command-name";
# this is the default
arguments = [ ];
};
}
Generally, however, this helper is not useful for nodeAppWithArgs
: the resulting node
invocation is always executed with the provided arguments
Flake app
app
- (Required)
A derivation containing an executable in a
bin
directory and which can be called by Node- Type
- derivation
Serve compiled documentation from localhost
Flake app
docs
- (Required)
A derivation containing the compiled project documentation in the correct directories (
generated-docs
). Can be obtained frombuildDocs
- Type
- derivation
port
-
The port on which the local webserver will run
- Type
- integer
- Default
-
8080
- Example
-
9999
Contains Javascript-specific utilities
Generates node_modules
. This is called inside spagoProject
and made available to users as it may be occasionally desirable to override the nodeModules
that are used in different project derivations (e.g. to include/exclude the devDependencies
listed in the package.json
). Contains lib
and bin
subdirectories, the former holding the node_modules
derivation
packageJson
- (Required)
Store path pointint to the
package.json
- Type
- path
packageLock
- (Required)
Store path pointint to the
package-lock.json
- Type
- path
name
-
String appended to the store path containing the generated modules
- Type
- string
- Default
-
""
- Example
-
"my-project" # produces `node-modules-my-project`
nodejs
-
The specific version of
nodejs
to use- Type
- derivation
- Default
-
pkgs.nodejs-14_x
- Example
-
pkgs.nodejs-18_x
spago
-
The specific version of
spago
to use- Type
- derivation
- Default
-
pkgs.purescriptPackages.spago
- Example
-
pkgs.purescriptPackages.spago-20_7
development
-
If
true
, thenodeModules
will contain alldevDependencies
- Type
- boolean
- Default
-
true
- Example
-
false
These functions are made available in the attribute set returned by spagoProject
. Because Spago has no mechanism for describing different project components (libraries, executables, tests, etc…), spago.nix
cannot generate outputs for you automatically (some outputs can be generated and put into the flake
attribute). To work around this, the following functions provide a more complete interface for different commands that spago
offers
Bundles the project into a CommonJS module using the provided main
module to the output filepath indicated by to
derivation
main
-
The main Purescript module to bundle (the module name, not a filepath), used as the bundled module’s entrypoint
- Type
- string
- Default
-
"Main"
- Example
-
"Package.Module.Main"
to
-
The target filepath that the bundled module will be written to
- Type
- string
- Default
-
"index.js"
- Example
-
"output.js"
name
-
Overrides the
name
used for the derivation, which is otherwise derived from thename
arg tospagoProject
- Type
- string
- Example
-
"my-bundled-module"
Bundles the project into an executable that can be run with Node, using the provided main
module to the output filepath indicated by to
. Note: Although this is bundled into an app, it cannot be run on its own and is mostly useful if you want to use it in another derivation. You will still need to call node
to execute it and set the NODE_PATH
if necessary. You can also use nodeApp
or nodeAppWithArgs
, both of which perform these steps for you.
derivation
main
-
The main Purescript module to bundle (the module name, not a filepath), used as the bundled app’s entrypoint
- Type
- string
- Default
-
"Main"
- Example
-
"Package.Module.Main"
to
-
The target filepath that the bundled app will be written to
- Type
- string
- Default
-
"index.js"
- Example
-
"output.js"
name
-
Overrides the
name
used for the derivation, which is otherwise derived from thename
arg tospagoProject
- Type
- string
- Example
-
"my-bundled-app"
Calls the Purescript entrypoint specified by testMain
without writing to $out
. Suitable for use as part of your flake checks
(if the returns a non-zero exit code, the check will fail)
derivation
testMain
-
The main Purescript module that acts as an entrypoint
- Type
- string
- Default
-
"Test.Main"
- Example
-
"Package.Module.Test.Main"
env
-
Environment or other variables; these are passed directly to
runCommand
. Can be useful if your test depends on looking up something in the environment- Type
- attribute set
- Default
-
{ }
- Example
-
{ ENV_VAR = "value"; }
nodeModules
-
Overrides the
nodeModules
used internally, which default to the project-wide ones- Type
- derivation
- Example
-
spago-nix.utils.js.mkNodeModules { development = false; /* snip */ }
name
-
Overrides the
name
used for the derivation, which is otherwise derived from thename
arg tospagoProject
- Type
- string
- Example
-
"my-test"
Calls the Purescript entrypoint (specified by testMain
) with Node and without writing to $out
. Provides the specified command
and arugments
to the Node invocation; this is useful if your test requires or parses specific arguments. Also suitable for use as part of your flake checks
(if the returns a non-zero exit code, the check will fail to build)
derivation
testMain
-
The main Purescript module that acts as an entrypoint
- Type
- string
- Default
-
"Test.Main"
- Example
-
"Package.Module.Test.Main"
command
-
The command-line name. Node’s
process.env.argv
includes this as the first argument, so if we didn’t include it then the first argument would become the command name (an undesirable result)- Type
- string
- Default
-
builtins.replaceStrings [ "." ] [ "-" ] (lib.strings.toLower testMain)
- Example
-
"my-test"
arguments
-
The arguments to provide to the command. These are joined into a single space-separated string and passed to the Node invocation
- Type
- list
- Default
-
[ ]
- Example
-
[ "--arg1" "val1" "--arg2" "val2" ]
env
-
Environment or other variables; these are passed directly to
runCommand
. Can be useful if your test depends on looking up something in the environment- Type
- attribute set
- Default
-
{ }
- Example
-
{ ENV_VAR = "value"; }
nodeModules
-
Overrides the
nodeModules
used internally, which default to the project-wide ones- Type
- derivation
- Example
-
spago-nix.utils.js.mkNodeModules { development = false; /* snip */ }
name
-
Overrides the
name
used for the derivation, which is otherwise derived from thename
arg tospagoProject
- Type
- string
- Example
-
"my-test"
Creates an executable from the Purescript entrypoint (specified by main
) that calls Node, installing it to $out/bin/name
. This is similar to bundleApp
above, but calls node
for you and also sets the correct NODE_PATH
using the nodeModules
that have been generated for the project (unless overridden)
derivation
main
-
The main Purescript module that acts as an entrypoint
- Type
- string
- Default
-
"Main"
- Example
-
"Package.Module.Main"
env
-
Environment or other variables. These are
export
ed in a script that is provided towriteShellApplication
, so you may want to useescapeShellArg
as this is not done for you automatically. Can be useful if your test depends on looking up something in the environment- Type
- attribute set
- Default
-
{ }
- Example
-
{ ENV_VAR = "value"; }
nodeModules
-
Overrides the
nodeModules
used internally, which default to the project-wide ones- Type
- derivation
- Example
-
spago-nix.utils.js.mkNodeModules { development = false; /* snip */ }
name
-
Overrides the
name
used for the derivation, which is otherwise derived from thename
arg tospagoProject
- Type
- string
- Example
-
"my-node-app"
Similar to nodeApp
above, but also allows for passing a command name and list of arguments. Note: This is useful if you want to call an application with the same set of arguments each time – specifically, those passed with the provided list of arguments
will always be used
derivation
main
-
The main Purescript module that acts as an entrypoint
- Type
- string
- Default
-
"Main"
- Example
-
"Package.Module.Main"
env
-
Environment or other variables. These are
export
ed in a script that is provided towriteShellApplication
, so you may want to useescapeShellArg
as this is not done for you automatically. Can be useful if your test depends on looking up something in the environment- Type
- attribute set
- Default
-
{ }
- Example
-
{ ENV_VAR = "value"; }
nodeModules
-
Overrides the
nodeModules
used internally, which default to the project-wide ones- Type
- derivation
- Example
-
spago-nix.utils.js.mkNodeModules { development = false; /* snip */ }
name
-
Overrides the
name
used for the derivation, which is otherwise derived from thename
arg tospagoProject
- Type
- string
- Example
-
"my-node-app"
Compiles the project documentation, either solely for dependencies if depsOnly
is enabled, or for all modules including the project sources (the default behavior).
Note: If you set the withDocs
argument to true
(the default value) in spagoProject
, a docs
attribute will be built and added to flake.packages
.
derivation
format
-
The format for the resulting compiled documentation
- Type
- one of ”
html
” or ”markdown
” - Default
-
"html"
- Example
-
"markdown"
depsOnly
-
If
true
, documentation will only be compiled for the project’s dependencies- Type
- boolean
- Default
-
false
- Example
-
true
This is a set returned from the spagoProject
function and contains the following attributes. Its structure mirrors the outputs
of a flake.nix
:
default
-
Contains a development environment corresponding to the options provided to
spagoProject
’sshell
argument. Irrespective of the selected options, it will always contain a version ofpurs
that corresponds to your upstream package set as well asspago
. Also aliased to thedevShell
attribute
output
-
This holds the
output
directory that is created bypurs
when compiling the project’s sources. It can be used in subsequent derivations. It copies thesrc
as well: if you read from a file from a relative path in your Purescript code,purs
doesn’t copy it into theoutput
directory. This behavior may change in the future. docs
-
This is only added to the
flake
ifwithDocs
is enabled (the default). It contains thegenerated-docs
andoutput
directory produced byspago docs
. It uses the default format (html
) and includes the project’s sources as well. If you setwithDocs
tofalse
, you can still build documentation with more customization options usingbuildDocs
(but it will not be automatically added to theflake
of course)
docs
-
As with
packages.docs
, this is only added to theflake
ifwithDocs
is enabled. It builds uses that derivation to serve documentation onlocalhost:8080
. If you do not enablewithDocs
, then you can usespago-nix.utils.apps.fromDocs
to create a local documentation server with more options
This is a set containing the Purescript packages used to build the project. It will always contain the version of purs
selected for your project as well as spago
. If you provide a list of tools
in the shell
argument to spagoProject
, it will also contain those (e.g. purs-tidy
).