9.3 KiB
9.3 KiB
Configuration Files
Pre-configured settings for each TypeDialog backend and environment.
Overview
Configuration files are organized by backend (CLI, TUI, Web) and environment (default, dev, production).
config/
├── cli/
│ ├── default.toml # Standard CLI settings
│ ├── dev.toml # Development (debugging enabled)
│ └── production.toml # Production (optimized, hardened)
├── tui/
│ ├── default.toml # Standard TUI settings
│ ├── dev.toml # Development features enabled
│ └── production.toml # Optimized for deployment
└── web/
├── default.toml # Standard web server settings
├── dev.toml # Development (hot reload)
└── production.toml # Hardened for production
```text
## Backend Configurations
### CLI Backend
**command-line interface** - Simple text-based forms for scripts and automation.
| Config | Purpose | Debug | Colors | Timeout |
| -------- | --------- | ------- | -------- | --------- |
| default | Standard | No | Yes | 300 s |
| dev | Development | Yes | Yes | 300 s |
| production | Production | No | Yes | 3600 s |
**Usage:**
```bash
typedialog --config config/cli/production.toml form.toml
```text
**Features:**
- Inline validation
- Optional mouse support
- Placeholder text display
- Help text display
### TUI Backend
**terminal user interface** - Interactive multi-panel forms with navigation.
| Config | Purpose | Borders | Animations | Render |
| -------- | --------- | --------- | ----------- | -------- |
| default | Standard | Rounded | Enabled | Auto |
| dev | Development | Double | Enabled | Debug |
| production | Production | Rounded | Disabled | Optimized |
**Usage:**
```bash
typedialog-tui --config config/tui/production.toml form.toml
```text
**Features:**
- 3-panel layout (fields, input, buttons)
- Mouse support
- Keyboard navigation
- Real-time field updates
### Web Backend
**HTTP server** - Browser-based forms with REST API.
| Config | Purpose | CORS | HTTPS | Rate Limit |
| -------- | --------- | ------ | ------- | ----------- |
| default | Standard | Localhost | No | Unlimited |
| dev | Development | Enabled | No | Unlimited |
| production | Production | Restricted | Required | 100/min |
**Basic Usage:**
```bash
typedialog-web form.toml
# Server starts on http://localhost:8080
```text
**With Options:**
```bash
# Load defaults from .ncl file
typedialog-web form.toml --defaults values.ncl
# Save results to file after form submission
typedialog-web form.toml --output result.json
# Combine with custom locale
typedialog-web form.toml --defaults config.ncl --output result.json --locale es-ES
# Run on custom port
typedialog-web form.toml --port 9000
```text
**Features:**
- HTML/CSS rendering
- CSRF protection
- Response caching
- Gzip compression
- Array field management (RepeatingGroup)
- Default value loading from Nickel (.ncl) or JSON
- Output to file (JSON format)
## Configuration by Environment
### Development Configuration
Enabled features for development and debugging:
```toml
# CLI Dev
debug_output = true
log_level = "debug"
show_field_types = true
# TUI Dev
show_field_indices = true
trace_rendering = false
# Web Dev
hot_reload = true
debug = true
logs = "/tmp/typedialog-web.log"
```text
**Usage:**
```bash
typedialog --config config/cli/dev.toml form.toml
typedialog-tui --config config/tui/dev.toml form.toml
typedialog-web --config config/web/dev.toml
```text
### Production Configuration
Hardened settings optimized for deployment:
```toml
# CLI Production
debug_output = false
log_level = "error"
show_placeholders = false
timeout = 3600
# TUI Production
enable_animations = false
render_throttle = 16ms
max_fps = 60
# Web Production
require_https = true
csrf_enabled = true
rate_limit = 100
cache_ttl = 3600
```text
**Usage:**
```bash
typedialog --config config/cli/production.toml form.toml
typedialog-tui --config config/tui/production.toml form.toml
typedialog-web --config config/web/production.toml
```text
## Common Settings
### Form Configuration
```toml
[form]
title = "Form Title"
description = "Optional description"
[form.validation]
validate_on_change = true
show_errors_inline = true
strict_validation = true
```text
### Output Configuration
```toml
[output]
format = "json" # json, yaml, toml, text
pretty_print = true
debug_output = false
```text
### Logging
```toml
[logging]
level = "info" # debug, info, warn, error
file = "/var/log/typedialog/app.log"
```text
## Custom Configuration
### Creating Custom Configurations
Create a new TOML file based on an environment template:
```bash
# Copy production config as base
cp config/cli/production.toml config/cli/custom.toml
# Edit for your needs
nano config/cli/custom.toml
# Use it
typedialog --config config/cli/custom.toml form.toml
```text
### Override Specific Settings
Use environment variables to override config:
```bash
# CLI Backend
export TYPEDIALOG_DEBUG=1
export TYPEDIALOG_LOG_LEVEL=debug
typedialog --config config/cli/default.toml form.toml
# TUI Backend
export TYPEDIALOG_TUI_BORDER=double
typedialog-tui --config config/tui/default.toml form.toml
# Web Backend
export TYPEDIALOG_WEB_PORT=3000
export TYPEDIALOG_WEB_CORS_ORIGINS="localhost,example.com"
typedialog-web --config config/web/default.toml
# Fragment Search Paths (All Backends)
export TYPEDIALOG_FRAGMENT_PATH="/path/to/fragments:/another/path/fragments"
# On Windows use semicolon separator
# set TYPEDIALOG_FRAGMENT_PATH=C:\fragments;D:\other\fragments
typedialog form.toml
```text
**TYPEDIALOG_FRAGMENT_PATH:**
Colon-separated list (semicolon on Windows) of directories to search for fragment files.
Fragments are reusable form components loaded via `includes` directive in group definitions.
Search order:
1. Form's directory (backward compatible)
2. Directories in TYPEDIALOG_FRAGMENT_PATH (left to right)
Example:
```bash
export TYPEDIALOG_FRAGMENT_PATH="/usr/local/share/typedialog/fragments:$HOME/.typedialog/fragments"
typedialog form.toml
```text
**For complete documentation on fragment search paths, see:**
[Fragment Search Paths](./fragment-search-paths.md) - Cascading search, use cases, troubleshooting
## CLI Backend Configuration Details
```toml
[terminal]
use_raw_mode = true # Enable raw terminal mode
enable_mouse = false # Mouse support
use_color = true # Colored output
[appearance]
theme = "default" # Color theme
show_help = true # Display field help
show_placeholders = true # Show placeholder text
[validation]
validate_on_change = true # Real-time validation
show_errors_inline = true # Inline error messages
[timeout]
max_duration = 3600 # Max form time (seconds)
input_timeout = 300 # Field input timeout
```text
## TUI Backend Configuration Details
```toml
[terminal]
use_raw_mode = true
enable_mouse = true
enable_scrolling = true
height = -1 # -1 = auto
width = -1 # -1 = auto
[ui]
show_borders = true
show_focus = true
highlight_on_hover = true
enable_animations = true
[appearance]
theme = "default"
border_style = "rounded" # rounded, double, simple
color_scheme = "default"
[keyboard]
vi_mode = false
emacs_mode = false
[performance]
render_throttle = 16 # milliseconds
max_fps = 60 # frames per second
```text
## Web Backend Configuration Details
```toml
[server]
host = "0.0.0.0"
port = 8080
workers = 4
[html]
css_framework = "none" # bootstrap, tailwind, none
inline_styles = false
responsive = true
dark_mode = true
[submission]
method = "post"
webhook_url = "https://api.example.com/forms"
redirect_on_success = true
redirect_url = "https://example.com/thank-you"
[security]
csrf_enabled = true
rate_limit = 100 # requests per minute
require_https = true
add_security_headers = true
[performance]
cache_static = true
cache_ttl = 3600
enable_compression = true
compression_threshold = 1024
```text
## Distribution Configurations
When creating release distributions, all configurations are included:
```bash
# Build and package
just distro::build-release
just distro::create-package
# Result includes all configs
distribution/typedialog-0.1.0/
├── config/
│ ├── cli/
│ ├── tui/
│ └── web/
└── ...
```text
Users can then choose configs during installation:
```bash
# Extract distribution
tar -xzf typedialog-0.1.0.tar.gz
cd typedialog-0.1.0
# Install
bash installers/install.sh
# Use specific config
typedialog --config ~/.config/typedialog/cli/production.toml form.toml
```text
## Best Practices
### Development
- Use `dev` configurations for local development
- Enable debugging and verbose logging
- Use shorter timeouts for faster iteration
### Testing
- Use `default` configurations for testing
- Run integration tests with all environments
### Production
- Always use `production` configurations
- Verify HTTPS is enabled (web backend)
- Set appropriate rate limits
- Configure logging to persistent location
- Test thoroughly in staging first
## Related Documentation
- [BUILD_AND_DISTRIBUTION.md](../BUILD_AND_DISTRIBUTION.md) - Build guide
- [DISTRIBUTION_WORKFLOW.md](../DISTRIBUTION_WORKFLOW.md) - Release workflow
- [README.md](../README.md) - Main documentation