Configuration

Configuration Areas

Lightna configuration is divided into two areas:

• Frontend – available during rendering on the frontend.
• Backend – available in the compiler, indexer, and other CLI processes.

Examples:

• module/config.yaml – global configuration
• module/config/frontend.yaml – frontend configuration
• module/config/backend.yaml – backend configuration
• module/config/*.yaml (excluding backend.yaml and frontend.yaml) – global configuration
• module/config/frontend/*.yaml – frontend configuration
• module/config/backend/*.yaml – backend configuration

Configuration Merging

Lightna merges the configuration using a deep merge algorithm in the following sequence:

1. Configuration from all modules, based on the order in which they are declared.
2. Current edition config.php.
3. Current edition env.php.

config.php / env.php

config.php – used to define project-specific values. It is tracked by VCS to ensure consistency across environments.

The env.php file is used to define environment-specific values, such as credentials and secrets. This file should be ignored by version control (VCS) to protect sensitive information. Avoid adding non-environment-related configurations to env.php, as this may cause incorrect builds in the pipeline where env.php does not exist. Instead, use YAML and config.php for cross-environment configurations.

Short Syntax

Short syntax can be used to access deep values:

router.bypass.rule.url_starts_with: [ custom/bypass/url ]

instead of

router:
  bypass:
    rule:
      url_starts_with:
        - custom/bypass/url

Available Configuration

Everything that affects the frontend or backend is configured through YAML config files, including the router, actions, indexer, entities, storages, compiler, plugins, CLI commands, and more.

To get a quick overview of the configuration, run ./cli config. This will print the configuration for the backend area in JSON format. In the YAML files, you can find additional explanations for certain settings in the comments.

Below is the basic configuration explained:

Session in Files:

    ...
    'session' => [
        'handler' => 'file',
    ],
    ...

Session in Redis:

    'storage' => [
        ...
        'session_redis' => [
            'options' => [
                'host' => 'localhost',
                'port' => 6379,
                'db' => 3,
                'data_type' => 'hash',
                'data_hash_field' => 'data',
            ],
        ],
        ...
    ],
    ...
    'session' => [
        'handler' => 'redis',
    ],
    ...

Where:

session_redis	The storage used by the redis session handler.
data_type, data_hash_field	Required only if the session is stored in a Redis hash field. In this case, set data_type = hash and specify the field name inside the hash using data_hash_field.

Router & Bypass

router:
  action:
    my_action_code1: MyProject\MyModule\Router\Action\MyAction1
    my_action_code2: MyProject\MyModule\Router\Action\MyAction2
  route:
    my_action1/postData: my_action_code1
    my_action2/render: my_action_code2
  bypass:
    file: app_index.php
    rule:
      url_starts_with:
        - excluded_url_1/
        - excluded_url_2(/|$)
      no_route: 404,
    cookie:
      name: null
      value: null

Where:

router.action	List of actions including custom ones
router.route	List of static routes where the key is the URL and the value is an action code
router.bypass	Configuration for when a request can be bypassed to the app
bypass.file	Enables bypass logic if present and requires the specified file when bypassing is relevant. File path is relative to the Lightna entry folder.
bypass.rule.url_starts_with	List of regular expressions to bypass if the URL starts with them
bypass.rule.no_route	Determines behavior for unknown URLs 404 – Render a 404 page in Lightna bypass – Allow bypassing if no static route or indexed route is found
bypass.cookie	Sets a secret cookie name and value to force bypassing even if Lightna recognizes the URL

Maintenance

    ...,
    'maintenance' => [
        'enabled' => false,
        'dir' => 'maintenance',
        'vary_name' => 'ENV_VARIABLE',
        'bypass' => [
            'cookie' => [
                'name' => null,
                'value' => null,
            ],
        ],
    ],
    ...,

Where:

enabled	Enable or disable maintenance mode
dir	Directory where custom maintenance pages can be located. The path is relative to the Lightna entry folder
vary_name	Environment variable name used to locate domain-specific pages in dir If the file dir/ENV_VARIABLE.phtml is found, it will be used If not found, dir/default.phtml will be used If neither is found, the internal Lightna template will be used
bypass.cookie	Sets a secret cookie name and value to force bypassing maintenance

Progressive Rendering

progressive_rendering: true

Progressive rendering allows a page to be sent incrementally as content is processed instead of waiting for all elements to finish rendering. Disabled by default as it is not yet widely familiar.

When progressive rendering is enabled, errors in individual blocks won't cause the entire page to return a 500 error. Instead, the page will load normally with a 200 response, and the failed block will display an error, as highlighted below in yellow:

This means monitoring should focus on block errors along with full-page 500 responses.

Page Cache Compatibility

If you choose to serve Lightna pages from edge cache, which can reduce network delays in some cases, you need to instruct Lightna to handle private blocks accordingly.

page_cache:
  type: edge

If enabled by specifying page_cache.type, Lightna will do the following on public (shared) pages:

• Skip rendering private blocks on the server and render them via JavaScript instead
• Deny session reads during server-side page rendering to prevent potential data leaks

Read Layout to learn more about private blocks.
Read Entity Index to understand how private and public pages are determined.

Planned improvements include tighter integration with edge caching, including automatic page invalidation for pages updated by the indexer.