Introduction

Nixago Extensions is a flake library which provides extensions for Nixago. The extensions are designed to quickly generate configuration files for common development tools. They abstract away the difficulty of templating by providing a clean interface.

Don't see the tool you're looking for? Raise an issue.

Extensions

This chapter contains documentation for each of the provided extensions.

Conform

This extension generates the .conform.yaml file for configuring Conform. It takes a simplified version of the configuration file:

• The top-level policies entry is removed
• The type and spec sections of the policy are removed

Instead, the plugin takes a set with the commit and license attributes (the two valid policy types), and the value is what would typically get placed under spec. This change reduces the overall nesting of the input.

Usage

Example input:

{
  commit = {
    header = {
      length = 89;
      imperative = true;
      case = "lower";
      invalidLastCharacters = ".";
    };
    gpg = {
      required = false;
      identity = {
        gitHubOrganization = "some-organization";
      };
    };
    conventional = {
      types = [
        "type"
      ];
      scopes = [
        "scope"
      ];
    };
  };
  license = {
    skipPaths = [
      ".git/"
      "build*/"
    ];
    allowPrecedingComments = false;
  };
}

This would produce the following .conform.yaml file:

policies:
  - spec:
      conventional:
        scopes:
          - scope
        types:
          - type
      gpg:
        identity:
          gitHubOrganization: some-organization
        required: false
      header:
        case: lower
        imperative: true
        invalidLastCharacters: .
        length: 89
    type: commit
  - spec:
      allowPrecedingComments: false
      skipPaths:
        - .git/
        - build*/
    type: license

Github Settings

This extension generates the .github/settings.yml file used by the Settings App.

Usage

The schema for the configuration file is detailed here. For example:

{
  data = {
    repository = {
      name = "repo-name";
      description = "description of repo";
      homepage = "https://example.github.io/";
      private = false;
    };
    labels = [
      {
        name = "bug";
        color = "CC0000";
        description = "An issue with the system";
      }
      {
        name = "feature";
        color = "#336699";
        description = "New functionality";
      }
    ];
    milestones = [
      {
        title = "milestone-title";
        description = "milestone-description";
        state = "open";
      }
    ];
  };
}

Produces the following .github/settings.yml:

labels:
  - color: CC0000
    description: An issue with the system
    name: bug
  - color: "#336699"
    description: New functionality
    name: feature
milestones:
  - description: milestone-description
    state: open
    title: milestone-title
repository:
  description: description of repo
  homepage: https://example.github.io/
  name: repo-name
  private: false

Just

This extension generates the .just file used by the Just task runner. It allows the creation of a .justfile by specifying a header and tasks:

Usage

{
  head = ''
    var := "value"
  '';
  tasks = {
    task1 = [
      ''echo "Doing the thing"''
      "@doThing"
    ];
  };
}

The configuration has two major sections. The first is the head field, a raw string prepended to the top of the file. This section is typically where global settings and variables are defined in the Justfile. The second is the tasks field, a map of task names to a list of their respective steps. Each step in the list should ideally encompass a single action (this is idiomatic for Justfiles); however, multiline strings will also work.

The above example will produce the following file contents:

var := "value"

task1:
    echo "Doing the thing"
    @doThing

Lefthook

This extension generates the lefthook.yml file for configuring Lefthook.

Usage

{
    data = {
        commit-msg = {
            scripts = {
                template_checker = { runner = "bash"; };
            };
        };
        pre-commit = {
            commands = {
                stylelint = {
                    tags = "frontend style";
                    glob = "*.js";
                    run = "yarn stylelint {staged_files}";
                };
                rubocop = {
                    tags = "backend style";
                    glob = "*.rb";
                    exclude = "application.rb|routes.rb";
                    run = "bundle exec rubocop --force-exclusion {all_files}";
                };
            };
            scripts = {
                "good_job.js" = { runner = "node"; };
            };
        };
    };
}

Produces the following lefthook.yml:

commit-msg:
  scripts:
    template_checker:
      runner: bash
pre-commit:
  commands:
    rubocop:
      exclude: application.rb|routes.rb
      glob: "*.rb"
      run: bundle exec rubocop --force-exclusion {all_files}
      tags: backend style
    stylelint:
      glob: "*.js"
      run: yarn stylelint {staged_files}
      tags: frontend style
  scripts:
    good_job.js:
      runner: node

Pre-commit

This extension generates the .pre-commit-config.yaml file used to configure pre-commit.

Usage

The extension accepts a simplified configuration format that significantly reduces the verbosity. When managing pre-commit with Nix, creating a single "local" repo entry and adding system hooks that call out to binaries in the Nix store is often desirable. The benefit of this approach is that Nix manages the versioning of the binaries, and you have greater control over how the hook operates.

The accepted format is as follows:

{
    nixpkgs-fmt = {
        entry = "${pkgs.nixpkgs-fmt}/bin/nixpkgs-fmt";
        language = "system";
        files = "\\.nix";
    }
}

The format is a set consisting of hook names as the keys and their configuration properties as values. The id and name fields of the hook configuration are set to the hook name (i.e., nixpkgs-fmt). The entry should point to the binary called by pre-commit. Setting language to "system" ensures that the entry is called with the default shell. Finally, setting files ensures that pre-commit only passes Nix files to this hook. The above configuration would produce the following pre-commit-config.yaml file:

repos:
  - hooks:
      - entry: /nix/store/pmfl7q4fqqibkfz71lsrkcdi04m0mclf-nixpkgs-fmt-1.2.0/bin/nixpkgs-fmt
        files: \.nix
        id: nixpkgs-fmt
        language: system
        name: nixpkgs-fmt
    repo: local

Prettier

This plugin generates the .prettierrc.json file for configuring Prettier. It provides two types: one that allows you to configure any valid API options and another for generating an ignore file.

Usage

The schema for the configuration file is detailed here. For example:

{
    config = {
      arrowParens = "always";
      bracketSpacing = true;
      tabWidth = 80;
    };
}

Produces the following .prettierrc.json:

{
  "arrowParens": "always",
  "bracketSpacing": true,
  "tabWidth": 80
}

Ignore type

The extension can also be configured to accept a list of glob patterns used to determine which files are excluded when prettier is run:

{
  [
    ".direnv"
    ".conform.yaml"
    ".prettierrc.json"
    "tests"
    "CHANGELOG.md"
    "lefthook.yml"
  ]
}

When calling the extension, change the type to ignore:

prettier { data = []; type = "ignore"; }