Apps Options

`appModules`

Additional modules to extend app configuration options.

This allows other modules to add functionality to each app, such as scaffolding, IDE support, deployment settings, etc.

These modules are applied to each app under stackpanel.apps.<appName>.<module>.

Property	Value
Type	`list of module`
Default	`[ ]`

Configuration options for defining and managing applications within the Stackpanel environment. This module allows you to declare app-specific settings, dependencies, and runtime configurations that integrate with the Stackpanel orchestration system.

Core configuration options are defined here. These options are extended by other modules to add functionality such as scaffolding, IDE support, and deployment settings. These are typically configured at stackpanel.apps.<appName>.<module>.

A core stackpanel feature and convention is that each app is assigned a stable, deterministic port based on the repo (organization/repo) and app/service name. This allows the port to be known ahead of time without having to pass it around manually.

This key will also be used as the default value by other modules lke Caddy to create virtual hosts for the app.

If you encounter a collision in the port calculation, you can set <appName> to a different name to get a different port range.

Property	Value
Type	`attribute set of (submodule)`
Default	`{ }`

Example:

{
  web = {
    name = "web";
    path = "apps/web";
    tls = true;
    # Go app example - enable go features
    go = {
      enable = true;
      # Watch directories for live reload
      watchDirs = [ "cmd" "pkg" "internal" ];
      # tools.go will be automatically created, add dev tools here
      tools = [
        "github.com/golangci/golangci-lint/cmd/golangci-lint"
      ];
      # By default, turborepo integration (package.json), air live reload (.air.toml),
      # tools.go is all scaffolded automatically, but can be suppressed here
      generateFiles = true;
    };
  };
  server = { offset = 1; };
  docs = { domain = "docs"; };
  api = { domain = "api"; tls = true; };
}

`apps.<name>.deploy`

Colmena deployment mapping for this app

Property	Value
Type	`submodule`
Default	`{ }`

`apps.<name>.deploy.enable`

Enable deployment mapping for this app

Property	Value
Type	`boolean`
Default	`false`

`apps.<name>.deploy.nixos-modules`

Extra NixOS modules to import for this app

Property	Value
Type	`list of string`
Default	`[ ]`

`apps.<name>.deploy.role`

Deployment role label for this app

Property	Value
Type	`null or string`
Default	`null`

`apps.<name>.deploy.secrets`

Secret references required by this app during deploy

Property	Value
Type	`list of string`
Default	`[ ]`

`apps.<name>.deploy.system`

Target system/architecture (e.g., x86_64-linux)

Property	Value
Type	`null or string`
Default	`null`

`apps.<name>.deploy.targets`

Target machine ids or tag selectors

Property	Value
Type	`list of string`
Default	`[ ]`

`apps.<name>.deployment.bindings`

Environment variable names to bind to the deployed app. Each name is read from process.env at deploy time. Mark sensitive ones in secrets.

Property	Value
Type	`list of string`
Default	`[ ]`

Example:

[
  "DATABASE_URL"
  "CORS_ORIGIN"
  "BETTER_AUTH_SECRET"
]

`apps.<name>.deployment.enable`

Whether to enable deployment for this app.

Property	Value
Type	`boolean`
Default	`false`

Example:

true

`apps.<name>.deployment.host`

Deployment host/platform. Combined with framework to determine the alchemy resource type:

framework × host → alchemy resource tanstack-start × cloudflare → TanStackStart nextjs × cloudflare → Nextjs vite × cloudflare → cloudflare.Vite hono × cloudflare → cloudflare.Worker

Property	Value
Type	`null or one of "cloudflare", "fly", "vercel", "aws"`
Default	`null`

Example:

"cloudflare"

`apps.<name>.deployment.secrets`

Subset of bindings that contain sensitive values. These are wrapped with alchemy.secret() at deploy time.

Property	Value
Type	`list of string`
Default	`[ ]`

Example:

[
  "DATABASE_URL"
  "BETTER_AUTH_SECRET"
]

`apps.<name>.description`

Description of the app

Property	Value
Type	`null or string`
Default	`null`

`apps.<name>.domain`

Local development domain

Property	Value
Type	`null or string`
Default	`null`

`apps.<name>.environments`

Environment configurations (key = environment name like "dev", "prod").

Property	Value
Type	`attribute set of (submodule)`
Default	`{ }`

`apps.<name>.environments.<name>.description`

(optional) Description of the environment

Property	Value
Type	`null or string`
Default	`null`

`apps.<name>.environments.<name>.env`

Environment variables for this environment. Key: Environment variable name (e.g., DATABASE_URL) Value: Literal string or vals reference (e.g., ref+sops://...)

Property	Value
Type	`attribute set of string`
Default	`{ }`

`apps.<name>.environments.<name>.name`

Name of the environment

Property	Value
Type	`string`
Default	`""`

`apps.<name>.framework.astro.enable`

Whether to enable Astro (static/SSR).

Property	Value
Type	`boolean`
Default	`false`

Example:

true

`apps.<name>.framework.hono.enable`

Whether to enable Hono API server.

Property	Value
Type	`boolean`
Default	`false`

Example:

true

`apps.<name>.framework.hono.entrypoint`

Entrypoint file for the Hono worker.

Property	Value
Type	`string`
Default	`"src/index.ts"`

`apps.<name>.framework.nextjs.enable`

Whether to enable Next.js (App Router or Pages).

Property	Value
Type	`boolean`
Default	`false`

Example:

true

`apps.<name>.framework.nextjs.output`

Next.js output mode.

Property	Value
Type	`one of "standalone", "export"`
Default	`"standalone"`

`apps.<name>.framework.nuxt.enable`

Whether to enable Nuxt.

Property	Value
Type	`boolean`
Default	`false`

Example:

true

`apps.<name>.framework.remix.enable`

Whether to enable Remix.

Property	Value
Type	`boolean`
Default	`false`

Example:

true

`apps.<name>.framework.tanstack-start.enable`

Whether to enable TanStack Start (full-stack SSR with TanStack Router + Nitro).

Property	Value
Type	`boolean`
Default	`false`

Example:

true

`apps.<name>.framework.vite.assets-dir`

Output directory for built assets.

Property	Value
Type	`string`
Default	`"dist"`

`apps.<name>.framework.vite.enable`

Whether to enable Vite SPA (React, Vue, Svelte, etc.).

Property	Value
Type	`boolean`
Default	`false`

Example:

true

`apps.<name>.framework.vite.ssr`

Enable Vite SSR mode.

Property	Value
Type	`boolean`
Default	`false`

`apps.<name>.name`

Display name of the app

Property	Value
Type	`string`
Default	`""`

`apps.<name>.offset`

Port offset from base port. If null, offset is determined by position in apps attrset.

Property	Value
Type	`null or signed integer`
Default	`null`

Example:

5

`apps.<name>.packageName`

NPM package name for turbo filter (e.g., "@stackpanel/web"). If null, defaults to the app name.

Property	Value
Type	`null or string`
Default	`null`

Example:

"@myorg/web"

`apps.<name>.path`

Relative path to the app directory

Property	Value
Type	`string`
Default	`""`

`apps.<name>.port`

Development server port

Property	Value
Type	`null or signed integer`
Default	`null`

`apps.<name>.tls`

Enable TLS for the vhost (requires Step CA)

Property	Value
Type	`boolean`
Default	`false`

`apps.<name>.tooling.build`

Build tool definition (wrapped).

Property	Value
Type	`null or (submodule)`
Default	`null`

`apps.<name>.tooling.build-steps`

Additional build steps (wrapped).

Property	Value
Type	`list of (submodule)`
Default	`[ ]`

`apps.<name>.tooling.build-steps.*.args`

Arguments passed to the tool.

Property	Value
Type	`list of string`
Default	`[ ]`

`apps.<name>.tooling.build-steps.*.bin`

Optional binary name if the package provides multiple executables.

Property	Value
Type	`null or string`
Default	`null`

`apps.<name>.tooling.build-steps.*.configArg`

Argument prefix inserted before configPath (e.g. ["--config"]).

Property	Value
Type	`null or (list of string)`
Default	`null`

`apps.<name>.tooling.build-steps.*.configPath`

Repo-relative config file path for the tool.

Property	Value
Type	`null or string`
Default	`null`

`apps.<name>.tooling.build-steps.*.cwd`

Override working directory (repo-relative). Defaults to app path.

Property	Value
Type	`null or string`
Default	`null`

`apps.<name>.tooling.build-steps.*.env`

Environment variables for the tool.

Property	Value
Type	`attribute set of string`
Default	`{ }`

`apps.<name>.tooling.build-steps.*.package`

Package that provides the tool binary.

Property	Value
Type	`package`
Default	none

`apps.<name>.tooling.build.args`

Arguments passed to the tool.

Property	Value
Type	`list of string`
Default	`[ ]`

`apps.<name>.tooling.build.bin`

Optional binary name if the package provides multiple executables.

Property	Value
Type	`null or string`
Default	`null`

`apps.<name>.tooling.build.configArg`

Argument prefix inserted before configPath (e.g. ["--config"]).

Property	Value
Type	`null or (list of string)`
Default	`null`

`apps.<name>.tooling.build.configPath`

Repo-relative config file path for the tool.

Property	Value
Type	`null or string`
Default	`null`

`apps.<name>.tooling.build.cwd`

Override working directory (repo-relative). Defaults to app path.

Property	Value
Type	`null or string`
Default	`null`

`apps.<name>.tooling.build.env`

Environment variables for the tool.

Property	Value
Type	`attribute set of string`
Default	`{ }`

`apps.<name>.tooling.build.package`

Package that provides the tool binary.

Property	Value
Type	`package`
Default	none

`apps.<name>.tooling.dev`

Dev tool definition (wrapped).

Property	Value
Type	`null or (submodule)`
Default	`null`

`apps.<name>.tooling.dev.args`

Arguments passed to the tool.

Property	Value
Type	`list of string`
Default	`[ ]`

`apps.<name>.tooling.dev.bin`

Optional binary name if the package provides multiple executables.

Property	Value
Type	`null or string`
Default	`null`

`apps.<name>.tooling.dev.configArg`

Argument prefix inserted before configPath (e.g. ["--config"]).

Property	Value
Type	`null or (list of string)`
Default	`null`

`apps.<name>.tooling.dev.configPath`

Repo-relative config file path for the tool.

Property	Value
Type	`null or string`
Default	`null`

`apps.<name>.tooling.dev.cwd`

Override working directory (repo-relative). Defaults to app path.

Property	Value
Type	`null or string`
Default	`null`

`apps.<name>.tooling.dev.env`

Environment variables for the tool.

Property	Value
Type	`attribute set of string`
Default	`{ }`

`apps.<name>.tooling.dev.package`

Package that provides the tool binary.

Property	Value
Type	`package`
Default	none

`apps.<name>.tooling.formatters`

Formatter definitions (wrapped).

Property	Value
Type	`list of (submodule)`
Default	`[ ]`

`apps.<name>.tooling.formatters.*.args`

Arguments passed to the tool.

Property	Value
Type	`list of string`
Default	`[ ]`

`apps.<name>.tooling.formatters.*.bin`

Optional binary name if the package provides multiple executables.

Property	Value
Type	`null or string`
Default	`null`

`apps.<name>.tooling.formatters.*.configArg`

Argument prefix inserted before configPath (e.g. ["--config"]).

Property	Value
Type	`null or (list of string)`
Default	`null`

`apps.<name>.tooling.formatters.*.configPath`

Repo-relative config file path for the tool.

Property	Value
Type	`null or string`
Default	`null`

`apps.<name>.tooling.formatters.*.cwd`

Override working directory (repo-relative). Defaults to app path.

Property	Value
Type	`null or string`
Default	`null`

`apps.<name>.tooling.formatters.*.env`

Environment variables for the tool.

Property	Value
Type	`attribute set of string`
Default	`{ }`

`apps.<name>.tooling.formatters.*.package`

Package that provides the tool binary.

Property	Value
Type	`package`
Default	none

`apps.<name>.tooling.install`

Install tool definition (wrapped).

Property	Value
Type	`null or (submodule)`
Default	`null`

`apps.<name>.tooling.install.args`

Arguments passed to the tool.

Property	Value
Type	`list of string`
Default	`[ ]`

`apps.<name>.tooling.install.bin`

Optional binary name if the package provides multiple executables.

Property	Value
Type	`null or string`
Default	`null`

`apps.<name>.tooling.install.configArg`

Argument prefix inserted before configPath (e.g. ["--config"]).

Property	Value
Type	`null or (list of string)`
Default	`null`

`apps.<name>.tooling.install.configPath`

Repo-relative config file path for the tool.

Property	Value
Type	`null or string`
Default	`null`

`apps.<name>.tooling.install.cwd`

Override working directory (repo-relative). Defaults to app path.

Property	Value
Type	`null or string`
Default	`null`

`apps.<name>.tooling.install.env`

Environment variables for the tool.

Property	Value
Type	`attribute set of string`
Default	`{ }`

`apps.<name>.tooling.install.package`

Package that provides the tool binary.

Property	Value
Type	`package`
Default	none

`apps.<name>.tooling.linters`

Linter definitions (wrapped).

Property	Value
Type	`list of (submodule)`
Default	`[ ]`

`apps.<name>.tooling.linters.*.args`

Arguments passed to the tool.

Property	Value
Type	`list of string`
Default	`[ ]`

`apps.<name>.tooling.linters.*.bin`

Optional binary name if the package provides multiple executables.

Property	Value
Type	`null or string`
Default	`null`

`apps.<name>.tooling.linters.*.configArg`

Argument prefix inserted before configPath (e.g. ["--config"]).

Property	Value
Type	`null or (list of string)`
Default	`null`

`apps.<name>.tooling.linters.*.configPath`

Repo-relative config file path for the tool.

Property	Value
Type	`null or string`
Default	`null`

`apps.<name>.tooling.linters.*.cwd`

Override working directory (repo-relative). Defaults to app path.

Property	Value
Type	`null or string`
Default	`null`

`apps.<name>.tooling.linters.*.env`

Environment variables for the tool.

Property	Value
Type	`attribute set of string`
Default	`{ }`

`apps.<name>.tooling.linters.*.package`

Package that provides the tool binary.

Property	Value
Type	`package`
Default	none

`apps.<name>.tooling.test`

Test tool definition (wrapped).

Property	Value
Type	`null or (submodule)`
Default	`null`

`apps.<name>.tooling.test.args`

Arguments passed to the tool.

Property	Value
Type	`list of string`
Default	`[ ]`

`apps.<name>.tooling.test.bin`

Optional binary name if the package provides multiple executables.

Property	Value
Type	`null or string`
Default	`null`

`apps.<name>.tooling.test.configArg`

Argument prefix inserted before configPath (e.g. ["--config"]).

Property	Value
Type	`null or (list of string)`
Default	`null`

`apps.<name>.tooling.test.configPath`

Repo-relative config file path for the tool.

Property	Value
Type	`null or string`
Default	`null`

`apps.<name>.tooling.test.cwd`

Override working directory (repo-relative). Defaults to app path.

Property	Value
Type	`null or string`
Default	`null`

`apps.<name>.tooling.test.env`

Environment variables for the tool.

Property	Value
Type	`attribute set of string`
Default	`{ }`

`apps.<name>.tooling.test.package`

Package that provides the tool binary.

Property	Value
Type	`package`
Default	none

`apps.<name>.type`

App type/runtime (bun, go, python, rust, etc.)

Property	Value
Type	`null or string`
Default	`null`

`appsComputed`

Computed app configurations with ports and URLs.

When pkgs is available, includes wrappedTooling derivations. When pkgs is not available (e.g., flake-parts top-level), wrappedTooling is null.

Property	Value
Type	`attribute set of attribute set of unspecified value`
Default	none
Read Only	`true`

apps

On this page