Add typed package options

Package options define the values cluster authors may place under an instance’s config. Kix validates those values while evaluating the cluster, before it renders Kubernetes manifests.

This guide extends the local package from Create a local package.

Declare the options

Add an options attribute beside meta and build:

how-to/application/web-package.nix (L24–L49)

  options = {
    message = lib.mkOption {
      type = lib.types.str;
      default = "Hello from Kix";
      description = "Text served from the application root.";
    };

    environment = lib.mkOption {
      type = lib.types.enum [
        "preview"
        "production"
      ];
      default = "preview";
      description = "Environment name exposed to the container.";
    };

    replicas = lib.mkOption {
      type = lib.types.ints.positive;
      default = 1;
      description = "Number of application replicas.";
    };

    healthCheck = kix.options.healthCheck;
  };

View source on GitHub ↗

Each lib.mkOption declaration can provide:

• type, which rejects values outside the package contract.
• default, which supplies a value when the instance omits the option.
• description, which explains the setting in generated reference material.
• example, when a useful value is not obvious from the default.

The example also composes kix.options.healthCheck, a shared option set. You can combine shared option sets with package-specific fields using //, as the post-deploy health-check guide demonstrates.

Read options from the build function

Add config to the build function arguments. Read evaluated values from that attribute set:

web-package.nix

build = {
  self,
  config,
  scope,
  kix,
  ...
}: {
  deployment = scope.mkDeployment {
    name = scope.instanceName;
    spec.replicas = config.replicas;
  };
};

config includes defaults as well as values set by the instance. Package code therefore does not need a separate fallback for replicas or environment.

Configure an instance

Set option values under config:

cluster.nix

instances.apps.web = {
  package = webPackage;
  config = {
    message = "Hello from production";
    environment = "production";
    replicas = 2;
  };
};

Fields not declared by the package are rejected. Values must also satisfy the declared type.

Check a validation error

For example, the package allows preview and production as environment names. Setting environment = "staging" produces this error:

Run in kix-examples/

❱ kix check how-to-application
 TOOL  RESULT  DETAILS                                                                                                                                                               
 eval  fail    could not read the built resources and their dependencies: nix build failed: warning: not writing modified lock file of flake 'path:kix-examples': 
               • Updated input 'kixpkgs':                                                                                                                                            
                   'git+https://github.com/kix-run/kixpkgs?ref=refs/heads/main&rev=9dcf5b3e33b728ef3fc76a693e4feda2921b1913' (2026-09-10)                                            
                 → 'path:/nix/store/1m3ijw2kvyj8z7cnnjac5h4qpl21wr1b-source/docs/..?lastModified=0&narHash=sha256-UxPEEja%2BlQ7yUWkJDR9yAydETmMgbnf8eRZ8%2Bx6m4%2BY%3D' (1970-01-01) 
               error:                                                                                                                                                                
                      … while calling the 'derivationStrict' builtin                                                                                                                 
                        at <nix/derivation-internal.nix>:37:12:                                                                                                                      
                          36|                                                                                                                                                        
                          37|   strict = derivationStrict drvAttrs;                                                                                                                  
                            |            ^                                                                                                                                           
                          38|                                                                                                                                                        
                                                                                                                                                                                     
                      … while evaluating the derivation attribute 'name'                                                                                                             
                        at /nix/store/4rg99msfmkk9gppakagpgkzcixwg7yxq-source/pkgs/stdenv/generic/make-derivation.nix:624:11:                                                        
                         623|         derivationArg = removeAttrs attrs removedOrReplacedAttrNames // {                                                                              
                         624|           ${if (attrs ? name || (attrs ? pname && attrs ? version)) then "name" else null} =                                                           
                            |           ^                                                                                                                                            
                         625|             let                                                                                                                                        
                                                                                                                                                                                     
                      … while evaluating the option `environment':                                                                                                                   
                                                                                                                                                                                     
                      (stack trace truncated; use '--show-trace' to show the full, detailed trace)                                                                                   
                                                                                                                                                                                     
                      error: A definition for option `environment' is not of type `one of "preview", "production"'. Definition values:                                               
                      - In `<unknown-file>': "staging"
(exit code: 1)

The error names the option and the rejected definition. Restore an allowed value and check the cluster again:

Run in kix-examples/

❱ kix check how-to-application
 TOOL         RESULT  DETAILS                                                       
 eval         pass    16 manifests evaluated                                        
 kubeconform  pass    skipped (this validation tool is not yet integrated with Kix) 
 pluto        pass    skipped (this validation tool is not yet integrated with Kix) 
 kyverno      pass    skipped (this validation tool is not yet integrated with Kix) 
 scorecard    pass    0 errors, 11 warnings, 2 info

Reference

See build, options, and root for the complete package interface.