Floco Packages Modules

Configuration Options

flocoPackages

Scope used for configuring flocoPackages framework.

Type: submodule

Declared by:

/floco/modules/packages/interface.nix

Package Options ( Builders )

flocoPackages.packages

Collection of built/prepared packages and modules.

Type: attribute set of attribute set of (submodule)

Declared by:

/floco/modules/packages/interface.nix

flocoPackages.packages.<name>.<name>.buildDependsOnLint

Causes the built lifecycle stage to be blocked by successful lint checking ( required lint to be non-null ).

This is recommended for projects which are under active development.

If preferMultipleOutputDerivations is enabled this is implemented by making the lint derivation an input of the built derivation. Otherwise this will cause a preBuild phase to run lint checks, killing the builder if the check fails.

NOTE: if built is an alias of source, this causes either installed or prepared to depend on lint instead.

Package Definition Options ( Translations )

flocoPackages.pdefs

List of pdef metadata records for all known pacakges and modules. These records are used to generate build recipes and build plans.

Type: attribute set of attribute set of (submodule)

Default: { }

Example:

{
  "@babel/cli" = {
    "7.20.7" = {
      "..." = "...";
      key = "@babel/cli/7.20.7";
    };
  };
  lodash = {
    "4.17.21" = {
      "..." = "...";
      key = "lodash/4.17.21";
    };
  };
}

Declared by:

/floco/modules/packages/interface.nix

flocoPackages.pdefs.<name>.<name>.ident

Package identifier/name as found in package.json:.name.

Type: string matching the pattern (@[^@/]+/)?[^@/]+

Example: "@floco/foo"

Declared by:

/floco/modules/pdef/interface.nix

flocoPackages.pdefs.<name>.<name>.key

Unique key used to refer to this package in tree submodules and other floco configs, metadata, and structures.

Type: string

Example: "@floco/foo/4.2.0"

Declared by:

/floco/modules/pdef/interface.nix

flocoPackages.pdefs.<name>.<name>.ltype

Package “lifecycle type”/”pacote source type”. This option effects which lifecycle events may run when preparing a package/module for consumption or installation.

For example, the file ( distributed tarball ) lifecycle does not run any scripts.[pre|post]build phases or result in any devDependencies being added to the build plan - since these packages will have been “built” before distribution. However, scripts.[pre|post]install scripts ( generally node-gyp compilation ) does run for the file lifecycle.

This option is effectively a shorthand for setting lifecycle defaults, but may also used by some fetchers and scrapers.

`binInfo`

flocoPackages.pdefs.<name>.<name>.binInfo

Indicates files or directories which should be prepared for use as executable scripts.

Type: submodule

Default:

{
  binDir = null;
  binPairs = { };
}

Declared by:

/floco/modules/pdef/binInfo/interface.nix

flocoPackages.pdefs.<name>.<name>.binInfo.binDir

Relative path to a subdir from which all files should be prepared as executables. Executable names will be defined as the basename of each file with any extensions stripped.

Type: null or string

Default: null

Declared by:

/floco/modules/pdef/binInfo/interface.nix

flocoPackages.pdefs.<name>.<name>.binInfo.binPairs

Pairs of { <EXE-NAME> = <REL-PATH>; ... } declarations mapping exposed executables scripts to their associated sources.

Type: attribute set of string

Default: { }

Declared by:

/floco/modules/pdef/binInfo/interface.nix

`depInfo`

flocoPackages.pdefs.<name>.<name>.depInfo

Information regarding dependency modules/packages. This record is analogous to the various package.json:.[dev|peer|optional|bundled]Dependencies[Meta] fields.

These config settings do note necessarily dictate the contents of the treeInfo configs, which are used by builders, but may be used to provide information needed to generate trees if they are not defined.

Type: attribute set of (attribute set of boolean)

Default: { }

Declared by:

/floco/modules/pdef/depInfo/interface.nix

flocoPackages.pdefs.<name>.<name>.depInfo.<name>.bundled

Whether the dependency is distributed in registry tarballs alongside the consumer.

This is sometimes used to include patched modules, but whenver possible bundling should be avoided in favor of tooling like esbuild or webpack because the effect bundled dependencies have on resolution is fraught.

Type: boolean

Default: false

Declared by:

/floco/modules/pdef/depInfo/single.interface.nix

flocoPackages.pdefs.<name>.<name>.depInfo.<name>.descriptor

Descriptor indicating version range or exact source required to satisfy a dependency.

The value "*" allows any version or source to be used, as long as it has the same identifier ( name ).

Type: string

Default: "*"

Declared by:

/floco/modules/pdef/depInfo/single.interface.nix

flocoPackages.pdefs.<name>.<name>.depInfo.<name>.dev

Whether the dependency is required during pre-distribution phases. This includes common tasks such as building, testing, and linting.

Type: boolean

Default: true

Declared by:

/floco/modules/pdef/depInfo/single.interface.nix

flocoPackages.pdefs.<name>.<name>.depInfo.<name>.optional

Whether the dependency may be omitted from the node_modules/ tree.

Conventionally this is used to mark dependencies which are only required under certain conditions such as platform, architecture, or engines. Generally optional dependencies carry sysInfo conditionals, or postinstall scripts which must be allowed to fail without blocking the build of the consumer.

Type: boolean

Default: false

Declared by:

/floco/modules/pdef/depInfo/single.interface.nix

flocoPackages.pdefs.<name>.<name>.depInfo.<name>.pin

An exact version number or URI indicating the “resolved” form of a dependency descriptor.

This will be used for treeInfo formation, and is available for usage by extensions to floco.

Type: null or string

Default: null

Declared by:

/floco/modules/pdef/depInfo/single.interface.nix

flocoPackages.pdefs.<name>.<name>.depInfo.<name>.runtime

Whether the dependency is required at runtime. Other package management tools often refer to these as “production mode” dependencies.

Type: boolean

Default: false

Declared by:

/floco/modules/pdef/depInfo/single.interface.nix

`fetchInfo`

flocoPackages.pdefs.<name>.<name>.fetchInfo

Arguments passed to fetcher. By default any `builtins.fetchTree’ or `builtins.path’ argset is supported, and the correct fetcher can be inferred from these values.

If set to `null’, `sourceInfo’ must be set explicitly.

Type: attribute set of (null or string or signed integer or boolean)

Declared by:

/floco/modules/pdef/interface.nix

`fsInfo`

flocoPackages.pdefs.<name>.<name>.fsInfo

Indicates information about a package that must be scraped from its source tree, rather than a conventional config file.

It is not recommended for users to manually fill these fields; rather we expect these to be informed by a cache or lockfile. You’re welcome to explicitly define them, but I don’t want to see anyone griping about these options in bug reports.

Type: submodule

Default:

{
  dir = ".";
  gypfile = false;
  shrinkwrap = false;
}

Declared by:

/floco/modules/pdef/fsInfo/interface.nix

flocoPackages.pdefs.<name>.<name>.fsInfo.dir

Relative path from sourceInfo.outPath to the package’s root. This field is analogous to a flake input’s dir field, and is used in combination with fetchInfo in exactly the same way as a flake input.

You should almost never need to set this field for distributed tarballs ( only if it contains bundled dependencies ).

While this field is useful for working with monorepos I strongly recommend that you avoid abusing it. Its use inherently causes rebuilds of all projects in associated with a single sourceInfo record for any change in the subtree. It is much more efficient to split a subtree into multiple sources, but I’ve left you enough rope to learn things the hard way if you insist on doing so. Consider yourself warned.

Type: string

Default: "."

Declared by:

/floco/modules/pdef/fsInfo/interface.nix

flocoPackages.pdefs.<name>.<name>.fsInfo.gypfile

Whether binding.gyp exists in the project root. May be explicitly overridden by declarations in package.json.

WARNING: You must not set this field based on ANY metadata pulled from a registry. There is a bug in NPM v8 that caused thousands of registry packuments and vinfo records to be poisoned, and in addition to that there is conflicting reporting rules for this field in POST requests by various package managers such that you should effectively disregard the value entirely.

Type: boolean

Default: false

Declared by:

/floco/modules/pdef/fsInfo/interface.nix

flocoPackages.pdefs.<name>.<name>.fsInfo.shrinkwrap

Whether npm-shrinkwrap.json exists in the project root. This is distributed form of package-lock.json which may be used to install exact dependencies during global installation of packages. For module/workspace installation this file takes precedence over package-lock.json if it exists.

The use of npm-shrinkwrap.json is only recommended for executables.

NOTE: floco does not use npm-shrinkwrap.json at this time, so this field exists as a stub.

Type: boolean

Default: false

Declared by:

/floco/modules/pdef/fsInfo/interface.nix

`lifecycle`

flocoPackages.pdefs.<name>.<name>.lifecycle

Enables/disables phases executed when preparing a package/module for consumption or installation.

Executing a phase when no associated script is defined is not necessarily harmful, but has a drastic impact on performance and may cause infinite recursion if dependency cycles exist among packages.

`metaFiles` ( Internal )

flocoPackages.pdefs.<name>.<name>.metaFiles.pjsDir

Path to the directory containing package.json. We require this path so that we can fetch source trees declared as relative paths in the package.json under dependencies ( and similar ) and workspaces fields.

NOTE: If your package.json contains ../* relative paths it is strongly recommended that this option be set to a non-store path. If a store path such as /nix/store/xxxxx-source/../some-dir is given, Nix will crash and burn attempting to fetch some-dir. A common trick to ensure that you are passing a regular filesystem path is to stringize as: pjsDir = toString ./.;.

Type: path

Example: "/home/camus/src/floco/modules/pdef/my-project"

Declared by:

/floco/modules/pdef/interface.nix

flocoPackages.pdefs.<name>.<name>.metaFiles.pjsKey

For package.json files with workspaces, the pjsKey is used to identify a workspace member.

These keys are simply a relative path from the “root” pjsDir to a sub-project’s pjsDir.

NOTE: This field is currently unused by floco, but is future extensions will use it to support workspaces.

Type: string

Default: ""

Declared by:

/floco/modules/pdef/interface.nix

flocoPackages.pdefs.<name>.<name>.metaFiles.plent

Raw contents of a package-lock.json:.packages.* record.

`peerInfo`

flocoPackages.pdefs.<name>.<name>.peerInfo

Set of propagated dependencies that consumers of this package/module must provide at runtime.

Often peer dependencies are used to enforce interface alignment across a set of modules but do not necessarily imply that the requestor depends on the declared peer at build time or runtime - rather it states “my consumers depend on the declared peer as a side effect of their dependence on me”.

NOTE: For the purposes of treeInfo and the construction of a node_modules/ tree, if a module declares a peer then that peer must be placed in a “sibling” or parent node_modules/ directory, and never as a subdirectory of the requestor! The “sibling” case is why the term “peer” is used, indicating that these modules must be “peers” living in the same node_modules/ directory; in practice a parent directory also works, but you get the idea.

Type: attribute set of (submodule)

Default: { }

Declared by:

/floco/modules/pdef/peerInfo/interface.nix

flocoPackages.pdefs.<name>.<name>.peerInfo.<name>.descriptor

Descriptor indicating version range or exact source required to satisfy a peer dependency.

The value "*" allows any version or source to be used, as long as it has the same identifier ( name ).

Type: string

Default: "*"

Declared by:

/floco/modules/pdef/peerInfo/single.interface.nix

flocoPackages.pdefs.<name>.<name>.peerInfo.<name>.optional

Whether consumers are required to provide the declared peer.

Optional peer declarations are conventionally used to handle platform or architecture dependant modules which are only required for certain systems - in general this field should be interpreted as “this peer dependency is required under certain conditions”. Often these conditions are audited using postinstall scripts, and as an optimization it may be worthwhile to ignore those audits if their conditions can be asserted in Nix ( for example if you know system, there’s no reason to use a derivation to run some JavaScript that probes and audits cpu and os ).

Type: boolean

Default: false

Declared by:

/floco/modules/pdef/peerInfo/single.interface.nix

`sourceInfo`

flocoPackages.pdefs.<name>.<name>.sourceInfo

Information about the source tree a package resides in. This record is analogous to that returned by builtins.fetchTree for flake inputs.

Used in combination with fetchInfo and fsInfo.dir, these three nuggets of metadata are isomorphic with a flake input.

However, unlike flake inputs, sourceInfo.outPath may set to a derived store path if and only if fetchInfo is explicitly set to null. In this case fsInfo.dir is still used to identify a pacakage/module’s root directory where we will attempt to read package.json ( must exist ) and similar metadata files will be read from ( if they exist ).

In this case you may avoid IFD by explicitly setting top level fields, specifically lifecycle, sysInfo, binInfo, and treeInfo or depInfo which are required by builders.

Alternatively you may explicitly set metaFiles.{pjs,plock,plent,trees} fields directly - but keep in mind that these fields are never guaranteed to be stable and their schema may change at any time ( so set the top level ones unless you`re up for the maintenance ).

Type: attribute set of (boolean or signed integer or string)

Declared by:

/floco/modules/pdef/interface.nix

flocoPackages.pdefs.<name>.<name>.sourceInfo.outPath

A Nix Store path containing the unpacked source tree in which this package/module resides. The package need not be at the root this path; but when the project root is a subdir the option `fsInfo.dir` must be set in order for `package.json` and other metadata to be translated.

Type: path

Declared by:

/floco/modules/pdef/interface.nix

`sysInfo`

flocoPackages.pdefs.<name>.<name>.sysInfo

Indicates platform, arch, and Node.js version support.

Type: submodule

Default:

{
  cpu = [
    "*"
  ];
  engines = {
    node = "*";
  };
  os = [
    "*"
  ];
}

Declared by:

/floco/modules/pdef/sysInfo/interface.nix

flocoPackages.pdefs.<name>.<name>.sysInfo.cpu

List of supported CPU architectures. The string "*" indicates that all CPUs are supported.

Type: list of (one of “*”, “x86_64”, “i686”, “aarch”, “aarch64”, “powerpc64le”, “mipsel”, “riscv64”, “unknown”)

Default:

[
  "*"
]

Declared by:

/floco/modules/pdef/sysInfo/interface.nix

flocoPackages.pdefs.<name>.<name>.sysInfo.engines

Indicates supported tooling versions.

Type: attribute set of string

Default:

{
  node = "*";
}

Declared by:

/floco/modules/pdef/sysInfo/interface.nix

flocoPackages.pdefs.<name>.<name>.sysInfo.engines.node

Supported Node.js versions.

Type: string

Default: "*"

Example: ">=14"

Declared by:

/floco/modules/pdef/sysInfo/interface.nix

flocoPackages.pdefs.<name>.<name>.sysInfo.os

List of supported operating systems. The string "*" indicates that all operating systems are supported.

Type: list of (one of “*”, “darwin”, “freebsd”, “netbsd”, “linux”, “openbsd”, “sunprocess”, “win32”, “unknown”)

Default:

[
  "*"
]

Declared by:

/floco/modules/pdef/sysInfo/interface.nix

`treeInfo`

flocoPackages.pdefs.<name>.<name>.treeInfo

node_modules/ trees used for various lifecycle events. These declarations are analogous to the package.* field found in package-lock.json(v2/3) files. This means that these fields should describe both direct and indirect dependencies for the full dependency graph.

Tree declarations are expected to be pairs of node_modules/ paths to “keys” ( matching the key field in its Nix declaration ):

{
  "node_modules/@foo/bar" = {
    key = "@foo/bar/1.0.0";
    dev = true;
    ...
  };
  "node_modules/@foo/bar/node_modules/baz" = {
    key = "baz/4.2.0";
    dev = false;
    ...
  };
  ...
}

In practice we expect users to explicitly define this field only for targets which they actually intend to create installables from, and we recommend using a package-lock.json(v2/3) to fill these values.

Type: null or (attribute set of (attribute set of boolean))

Default: null

Declared by:

/floco/modules/pdef/treeInfo/interface.nix

flocoPackages.pdefs.<name>.<name>.treeInfo.<name>.dev

Whether the dependency is required ONLY during pre-distribution phases. This includes common tasks such as building, testing, and linting.

Type: boolean

Default: false

Declared by:

/floco/modules/pdef/treeInfo/single.interface.nix

flocoPackages.pdefs.<name>.<name>.treeInfo.<name>.key

Unique key used to refer to this package in tree submodules and other floco configs, metadata, and structures.

Type: null or string

Default: null

Declared by:

/floco/modules/pdef/treeInfo/single.interface.nix

flocoPackages.pdefs.<name>.<name>.treeInfo.<name>.optional

Whether the dependency may be omitted from the node_modules/ tree.

Conventionally this is used to mark dependencies which are only required under certain conditions such as platform, architecture, or engines. Generally optional dependencies carry sysInfo conditionals, or postinstall scripts which must be allowed to fail without blocking the build of the consumer.

Type: boolean

Default: false

Declared by:

/floco/modules/pdef/treeInfo/single.interface.nix

flocoPackages.pdefs.<name>.<name>.version

Package version as found in package.json:.version.

Example: "4.2.0"

Declared by:

/floco/modules/pdef/interface.nix

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Floco Packages Modules

Floco Packages Modules

Configuration Options

Package Options ( Builders )

Package Definition Options ( Translations )

`binInfo`

`depInfo`

`fetchInfo`

`fsInfo`

`lifecycle`

`metaFiles` ( Internal )

`peerInfo`

`sourceInfo`

`sysInfo`

`treeInfo`

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

Floco Packages Modules

Floco Packages Modules

Configuration Options

Package Options ( Builders )

Package Definition Options ( Translations )

binInfo

depInfo

fetchInfo

fsInfo

lifecycle

metaFiles ( Internal )

peerInfo

sourceInfo

sysInfo

treeInfo

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

`binInfo`

`depInfo`

`fetchInfo`

`fsInfo`

`lifecycle`

`metaFiles` ( Internal )

`peerInfo`

`sourceInfo`

`sysInfo`

`treeInfo`