Skip to main content
Wik/Lex ships in dev mode by default. Switching to production mode eliminates all source-file I/O per request, disables the debugger, and serves templates from a precompiled index — giving you the fastest possible render path.

​
Dev mode vs production mode

BehaviourDev mode (default)Production mode
Source file mtime checkOn every render() callNever
Automatic recompilationYes — when source changesNo
LexDebugger activeYesNo
__lex_debug__ payload injectedYesNo
Precompiled index usedNoYes
Source I/O per requestYesZero

​
Dev mode

In dev mode, every render() call checks whether the source .lex file’s filemtime has changed since it was last compiled. If it has, the template is recompiled automatically. LexDebugger is active and injects a __lex_debug__ JSON payload into the rendered HTML, which powers the Chrome DevTools extension. Dev mode is the default — you do not need to configure anything to use it.

​
Production mode

In production mode, all source-file I/O is skipped. The engine looks up each template in a precompiled index (.lexer/compiled/index.php) and serves the compiled PHP file directly — no mtime checks, no recompilation, no disk reads beyond the compiled file itself. LexDebugger is disabled automatically; no debug data is ever injected into responses.
In production mode Lex never recompiles templates automatically. You must recompile after any template changes and redeploy the compiled output alongside your application code.

​
Enabling production mode

Set "production": true in your config file:
{
  "viewPaths":  ["views", "resources/views"],
  "production": true,
  "sandbox":    false
}
Lexer::fromConfig() reads this value on startup and enables production mode automatically.

​
Deployment workflow

1

Compile all templates

Before deploying, run the Lex CLI compile command. It walks every template in your configured view paths, runs the full compilation pipeline for each one, and writes the compiled PHP files to .lexer/compiled/.
vendor/bin/lex compile
This also builds the precompiled index at .lexer/compiled/index.php.
2

Deploy compiled output

Include the .lexer/ directory in your deployment. The engine reads index.php from it at startup in production mode — without it, templates cannot be served.
If you normally exclude .lexer/ from version control (recommended for dev), make sure your CI/CD pipeline runs lex compile after checkout and before packaging the deployment artifact.
3

Enable production mode

Set "production": true in lex.config.json or call ->setProduction() in your application bootstrap. The engine will use the precompiled index from step 1.
4

Recompile after template changes

Any time you change a .lex template, run lex compile again and redeploy. In production mode the engine never checks source mtimes, so stale compiled files will serve outdated output until you recompile.
vendor/bin/lex compile && your-deploy-command

​
The precompiled index

The index file lives at .lexer/compiled/index.php and is a plain PHP file that returns an associative array mapping absolute template paths to their corresponding compiled file paths: 
<?php

// Wik/Lexer precompiled view index — do not edit.

return array (
  '/var/www/app/views/home.lex' => '/var/www/app/.lexer/compiled/a1b2c3d4.php',
  '/var/www/app/views/layouts/app.lex' => '/var/www/app/.lexer/compiled/e5f6a7b8.php',
  // ...
);
In production mode FileCache::indexLookup() performs a single array key lookup per render call. If the compiled file exists on disk, it is served immediately — there are no further filesystem reads before execution.
Do not edit index.php by hand. It is written atomically by FileCache during compilation and will be overwritten the next time you run lex compile.

​
LexDebugger

LexDebugger is the layer that wraps render() in dev mode. It collects component tree data, section contents, cache hit/miss events, and render timing, then serialises them as a __lex_debug__ JSON payload appended to the HTML response. In production mode setProduction() sets an internal flag that causes render() to call ViewEngine::render() directly, bypassing LexDebugger entirely — there is no conditional check at render time, and no debug data is ever allocated or serialised.

Build docs developers (and LLMs) love

Get started for freeTalk to us