App Development

App Manifest

Declare the settings your app needs in laioutr.manifest.json, so customers enter them per environment in the Cockpit with a form, encrypted secrets and a connection test.

Your app talks to an external service, and every customer has their own account there: an API address, a token, a store id. Without a manifest, someone has to write those values into laioutrrc.json by hand for every environment. With a laioutr.manifest.json in your package, the Cockpit shows a form for them under each environment's Configuration, stores tokens encrypted, and offers a Test connection button that proves the values work before anyone deploys.

laioutr.manifest.json
{
  "configSettings": {
    "menu": { "label": "Acme Search" },
    "sections": [
      {
        "label": "Account",
        "fields": [
          { "name": "accountId", "type": "text", "label": "Account ID", "required": true },
          { "name": "apiToken", "type": "secret", "label": "API token" }
        ]
      }
    ]
  }
}

Each field's name is an option of your Nuxt module. The value a customer saves reaches your module exactly as if it had been written into laioutrrc.json under apps[].config, so your module code does not change. See App Configuration for how the module reads its options.

Names, never values

The manifest describes which settings your app asks for and how to show them. It never carries a customer's value. A token, a key or a default credential in the manifest would ship inside your package to everyone who installs it, and to the registry.

The validator enforces part of this: a secret field may not declare a default. The rest is up to you. Use placeholder to show the shape of a value (acme-shop.example.com), never a real one.

Where the file lives

Put laioutr.manifest.json at the root of your package, next to package.json, and list it in files. npm only packs what files names, and the registry reads the manifest from the published tarball. A manifest that is not in the tarball does not exist as far as the Cockpit is concerned.

package.json
{
  "name": "@laioutr-org/acme__search",
  "version": "1.4.0",
  "files": ["dist", "CHANGELOG.md", "laioutr.manifest.json"]
}

Check it with npm pack --dry-run: the file list must include laioutr.manifest.json.

The registry at npm.laioutr.cloud reads the manifest once, when a version is published, and keeps it with that version. A manifest belongs to one version: when you change it, publish a new version. The file may be at most 256 KB.

Publishing alone does not show the form yet. Releasing an App covers the step that hands it to the Cockpit.

Format

The manifest is a JSON object. Today it has one key, configSettings.

sections
AppConfigSection[] required
The groups of fields, shown in this order. At least one.
menu
{ label?: string; icon?: string }
label names the app's settings in the Cockpit. When left out, the Cockpit uses the app's catalogue title; for an app listed by its first release, that is the last segment of the package name (search for @laioutr-org/acme__search), so set a label. icon is accepted but not shown today.
placement
'environment' | 'project' | 'organization' | 'studio'
Where the settings are set. Only environment is rendered today: whatever you declare, the Cockpit shows the form per environment. Leave it out or set environment.
label
string
The section's heading. Required when the section has a test, and then unique among the sections that have one.
description
string
A line under the heading. A good place to say where in the external service the customer finds the values.
fields
AppConfigField[] required
The fields of the section. At least one.
test
AppConnectionTest
A request the Cockpit sends to prove the section's values work. See Connection tests.
placement
string
Accepted with the same values as above, not rendered today.
name
string required
The module option the value is stored under. A top-level field's name is unique across all sections of the manifest, because your module receives one options object; a field inside an object has a name unique across that object's fieldsets. A name holds no . and does not start with $.
type
string required
One of the types in the table below.
label
string
The field's label. Defaults to name.
description
string
Help text under the field.
placeholder
string
Shown in an empty text, textarea, secret or json field.
required
boolean
The Cockpit refuses to save the app's settings while a required field is empty.
default
string | number | boolean
What the form starts with when nothing is stored yet. Not allowed on secret. It pre-fills the form only; it is not a fallback your module receives when the field is empty.
options
{ value: string; label: string }[]
The choices of a select, radio or toggle_button. At least one for select and radio.
schema
{ label?: string; description?: string; fields: Field[] }[]
The fieldsets of an object, as in a section definition. Their fields are the keys of the object; the fieldsets only group them on screen. At least one fieldset with at least one field. See Grouped options.
minLength / maxLength
number
Length limits for text values.
pattern
string
A regular expression a text value must match.
min / max
number
Limits for a number.

Mark a field required only when your module cannot start without it. A required field blocks saving every other setting of the app in that environment until it has a value, including for a customer whose value still comes from somewhere else, such as an environment variable on their host.

Field types

typeThe Cockpit showsYour module receives
textA single-line inputstring
textareaA multi-line inputstring
numberA number input, checked against min and maxnumber
selectA dropdown of optionsthe chosen option's value
radioRadio buttons of optionsthe chosen option's value
checkboxA checkboxboolean
secretA password input. Stored encrypted; afterwards shown as bullets plus its last four characters (only for values of 20 characters or more), never in fullstring
infoA notice with label and description, no inputnothing
toggle_buttonA dropdown of optionsthe chosen option's value
objectIts fields under its label, each shown for its type; only its secret fields are stored encryptedan object of its fields' values
jsonA JSON text area, shown again as formatted JSONthe object
json with "secret": trueA JSON text area. Stored encrypted as one value; afterwards shown only as setthe object
richtext, arrayA note that the Cockpit cannot edit this type yet. A stored value is kept as it iswhatever is stored

An empty optional field is removed from the stored settings, so your module sees the option as not set and applies its own default.

Grouped options

Some modules read a group of options as one object:

src/module.ts
export interface ModuleOptions {
  kioskApi?: { url: string; token: string };
}

Declare such a group as an object field, as a section or block definition declares one: its schema holds fieldsets, and their fields are the keys of the object. An object may hold another object, to any depth.

laioutr.manifest.json
{
  "name": "kioskApi",
  "type": "object",
  "label": "Kiosk API",
  "schema": [
    {
      "fields": [
        { "name": "url", "type": "text", "label": "URL", "placeholder": "https://kiosk.example.com" },
        { "name": "token", "type": "secret", "label": "Token" }
      ]
    }
  ]
}

Each field inside the object is shown, checked and stored as it would be at the top level. The customer sees and edits the URL; only the token is stored encrypted and shown as bullets plus its last four characters. Your module receives kioskApi: { url, token }, the same object it always read. When every field of an object is empty, your module receives no kioskApi at all.

  • Mark the secret fields inside the object secret. An object itself cannot be secret.
  • required counts on the fields inside an object, not on the object.
  • A connection test fills placeholders from top-level text and number fields only, so a field inside an object cannot be one.
  • Read without secrets — laioutr rc fetch for a local run — the object arrives without its secret fields, as a top-level secret is left out too. A module that checks for kioskApi and then uses its token gets no token there.

JSON groups

A group can also be one json field, which the customer types as a whole, as JSON text:

  • Open ("type": "json"): stored as it was typed and shown again as formatted JSON.
  • Sealed ("type": "json", "secret": true): stored encrypted as one value and shown only as set, never any part of it, not even its last characters. To change one value inside it, the customer pastes the whole group again.

Prefer an object when you can choose. Each of its fields gets its own label, validation and help text, and a customer can still read the values that are no secret. A JSON group gets none of that: the Cockpit only checks that the text is JSON.

An app that declared a sealed JSON group can declare it as an object in its next version. The Cockpit then shows the stored group field by field, and its next save stores each field on its own, so nobody types a value again. A key of the stored group that the object does not declare stays encrypted. An environment that moves back to a version with the sealed group keeps working with what is stored.

Validation rules

A manifest that breaks a rule gives the app no settings form; publishing still succeeds. The rules:

  • configSettings.sections has at least one section, and each section has at least one field.
  • Every field has a name, unique across all sections, or for a field inside an object across that object's fieldsets. __proto__, constructor and prototype are not allowed, a name holds no ., and it does not start with $, which the Cockpit keeps for stored secrets.
  • Every type is one of the field types above.
  • A secret field has no default.
  • A select or radio field has at least one option.
  • An object has a schema with at least one fieldset that has fields, and is not secret. Every field inside it follows these rules too, at any depth.
  • placement, wherever it appears, is one of environment, project, organization, studio.
  • A section with a test has a label, and no other section with a test has the same label.
  • A test follows the rules in Connection tests.

Run the same validator before you publish. It returns a list of problems, each with the path it was found at, and an empty list for a sound manifest:

scripts/check-manifest.ts
import { readFileSync } from 'node:fs';
import { validateAppManifest } from '@laioutr-core/core-types/app';

const manifest = JSON.parse(readFileSync('laioutr.manifest.json', 'utf8'));
const problems = validateAppManifest(manifest);

if (problems.length) {
  console.error(problems.join('\n'));
  process.exit(1);
}
configSettings.sections[1].fields[2].options: a select needs at least one option

Connection tests

A section can declare one request that proves its values reach the service. The Cockpit shows a Test connection button on that section and sends the request from its server with the values on screen; values the customer has not changed come from what is stored, secrets included.

laioutr.manifest.json
{
  "label": "Account",
  "description": "Acme dashboard > Settings > API keys.",
  "fields": [
    { "name": "apiHost", "type": "text", "label": "API host", "placeholder": "eu.api.acme.example.com" },
    { "name": "apiToken", "type": "secret", "label": "API token" }
  ],
  "test": {
    "hosts": ["*.api.acme.example.com"],
    "method": "GET",
    "url": "https://{{apiHost}}/v1/account",
    "headers": { "Authorization": "Bearer {{apiToken}}" },
    "expect": "account.id"
  }
}
hosts
string[] required
The hosts the request may reach: an exact name (api.acme.example.com) or a wildcard for subdomains (*.acme.example.com). No IP addresses, no ports, no bare *, no internal names such as localhost or *.local.
method
'GET' | 'POST' required
Choose a request that reads and changes nothing in the customer's account.
url
string required
An https:// address. May contain placeholders, but never a secret one.
headers
Record<string, string>
Request headers. The place for a token.
body
string
A request body, with POST only.
expect
string
A dotted path into the JSON answer, such as data.shop.name. The test passes only when it holds a value. Without it, any 2xx answer passes.

{{name}} in the URL, a header or the body is replaced by the value of the field with that name. Any field of the manifest may be used, also one from another section; every placeholder must name a field, and only text and number values fill one. A secret goes in a header or the body, never the URL: an address ends up in logs and error messages, so the validator refuses a secret placeholder there.

How the Cockpit runs the test:

  • A value is encoded where it lands in the URL, so it can name a host but cannot add a path, a query or a fragment.
  • The resulting host must match hosts, use https with no port, and resolve to a public address. A private, loopback or link-local address is refused.
  • Redirects are not followed. The request times out after 10 seconds.
  • The browser learns only whether the test passed or why not: a value is missing, the host is not allowed, the service did not answer, it refused the credentials (401/403), nothing answered at that address (404), or another answer. It never sees the request address, the answer or any part of a credential.

A test is a check the customer starts by hand. It never runs on save or before a deployment.

A complete example

An app for a fictional search service, Acme Search, with an account, an index and two optional behaviours:

laioutr.manifest.json
{
  "configSettings": {
    "placement": "environment",
    "menu": { "label": "Acme Search" },
    "sections": [
      {
        "label": "Account",
        "description": "Acme dashboard > Settings > API keys. Use a read-only key.",
        "fields": [
          {
            "name": "apiHost",
            "type": "text",
            "label": "API host",
            "placeholder": "eu.api.acme.example.com",
            "required": true,
            "pattern": "^[a-z0-9.-]+$"
          },
          {
            "name": "apiToken",
            "type": "secret",
            "label": "API token",
            "required": true
          }
        ],
        "test": {
          "hosts": ["*.api.acme.example.com"],
          "method": "GET",
          "url": "https://{{apiHost}}/v1/account",
          "headers": { "Authorization": "Bearer {{apiToken}}" },
          "expect": "account.id"
        }
      },
      {
        "label": "Index",
        "fields": [
          {
            "name": "indexName",
            "type": "text",
            "label": "Index name",
            "description": "The index this environment searches. Use a separate index per environment.",
            "placeholder": "products-production"
          },
          {
            "name": "resultsPerPage",
            "type": "number",
            "label": "Results per page",
            "min": 1,
            "max": 100,
            "default": 24
          },
          {
            "name": "sortOrder",
            "type": "select",
            "label": "Default sort order",
            "options": [
              { "value": "relevance", "label": "Relevance" },
              { "value": "newest", "label": "Newest first" }
            ],
            "default": "relevance"
          }
        ]
      },
      {
        "label": "Behaviour",
        "fields": [
          {
            "name": "behaviourNote",
            "type": "info",
            "label": "Applies to the storefront search only",
            "description": "Category pages are not affected."
          },
          {
            "name": "typoTolerance",
            "type": "checkbox",
            "label": "Tolerate typos",
            "default": true
          }
        ]
      }
    ]
  }
}

The module that reads these settings:

src/module.ts
export interface ModuleOptions {
  apiHost: string;
  apiToken: string;
  indexName?: string;
  resultsPerPage?: number;
  sortOrder?: 'relevance' | 'newest';
  typoTolerance?: boolean;
}

Every name in the manifest is a key of ModuleOptions, except the info field, which holds no value. A unit test that reads the manifest and compares its field names with the keys of ModuleOptions catches a renamed option before a customer does.

Next steps

Copyright © 2026 Laioutr GmbH