DOCSEARCHbyAlgolia
Submit Docs

StyLua Documentation

repository·main·Indexed 25 days ago

https://github.com/johnnymorganz/stylua

A deterministic code formatter for Lua (5.1-5.4, LuaJIT, Luau, and CfxLua/FiveM) inspired by Prettier. It enforces a consistent code style based primarily on the Roblox Lua Style Guide. StyLua provides a CLI, LSP support, and integration for VS Code and pre-commit hooks. It supports custom configuration via stylua.toml and .editorconfig, glob filtering, and safety verification via the --verify flag.

Tokens
9.7K
Snippets
13
Records
58
Agent score
80%

What's inside StyLua

  1. Locate StyLua configuration files

    main

    StyLua searches for configuration files starting from the directory of the file being formatted and moving upwards to the current working directory.

    It looks for files in this order:

    1. stylua.toml or .stylua.toml
    2. .editorconfig (if no StyLua config is found)
    3. Default configuration (if no config files are found)

    Key Commands:

    • Use --no-editorconfig to disable searching for .editorconfig files.
    • Use --config-path <path> to specify a custom configuration file path. If the file is missing or malformed, StyLua will exit with an error.
    • Use --search-parent-directories to enable recursive searching of parent directories. If no config is found in the directory tree, StyLua will then check $XDG_CONFIG_HOME, $XDG_CONFIG_HOME/stylua, $HOME/.config, and $HOME/.config/stylua.

    Best Practice: It is highly recommended to keep a .stylua.toml file in your project root to ensure consistent formatting across different environments and avoid conflicts caused by searching outside the project directory.

  2. Configure pre-commit hooks for StyLua

    main

    You can integrate StyLua into your workflow using pre-commit. There are three hook types available:

    • stylua: Installs via cargo (requires Rust toolchain).
    • stylua-system: Runs a stylua binary already present on your PATH.
    • stylua-github: Automatically installs the correct prebuilt binary from GitHub Releases.

    Add this to your .pre-commit-config.yaml:

    - repo: https://github.com/JohnnyMorganz/StyLua
  rev: v2.5.2
  hooks:
    - id: stylua # or stylua-system / stylua-github

  3. Configure StyLua as the default formatter in VS Code

    main

    To use the StyLua extension for automatic formatting, you must set it as the default formatter for Lua files. You can do this by selecting StyLua when prompted by VS Code, or by manually adding the following configuration to your settings.json file.

    For standard Lua files:

    "[lua]": {
    "editor.defaultFormatter": "JohnnyMorganz.stylua"
}

    If you are working with Luau code, you should also add the configuration for the luau namespace:

    "[luau]": {
    "editor.defaultFormatter": "JohnnyMorganz.stylua"
}

  4. Configure Lua syntax disambiguation

    main

    By default, StyLua uses a union of all supported Lua syntax styles. If syntax styles conflict (for example, Lua 5.2's goto labels vs Luau's type assertions), you must explicitly specify the syntax style.

    You can set the syntax style in your .stylua.toml file or via the CLI.

    Supported Syntax Options:

    • All (default)
    • Lua51
    • Lua52
    • Lua53
    • Lua54
    • LuaJIT
    • Luau
    • CfxLua
    syntax = "Lua52"

    Or via CLI:

    stylua --syntax lua52 ...

  5. Format Lua code with StyLua

    main

    Once configured, you can format your code using the following methods:

    1. Format Document: Run the Format Document command via the Command Palette (CMD/CTRL + Shift + P).
    2. Format Selection: Highlight a specific block of code and run the Format Selection command.
    3. Format on Save: Enable the VS Code setting editor.formatOnSave to automatically format your files whenever you save them.

  6. Install StyLua via various methods

    main

    StyLua can be installed through several package managers and methods depending on your environment:

    GitHub Releases

    Download pre-built binaries from the GitHub Releases Page. These binaries include all syntax variants (Lua 5.2, 5.3, 5.4, LuaJIT, and Luau) by default.

    Rust (Crates.io)

    Install via cargo. By default, this builds for Lua 5.1. To support other versions, use the --features flag:

    # Lua 5.1 (default)
cargo install stylua

# Other variants
cargo install stylua --features lua52
cargo install stylua --features lua53
cargo install stylua --features lua54
cargo install stylua --features luajit
cargo install stylua --features luau

    npm

    Use the @johnnymorganz/stylua-bin wrapper via npx:

    npx @johnnymorganz/stylua-bin --help

    Alternatively, use @johnnymorganz/stylua as a WASM library for Node.js or browser environments.

    Docker

    Copy the binary from the official image:

    COPY --from=JohnnyMorganz/StyLua:2.5.2 /stylua /usr/bin/stylua

    Homebrew (macOS)

    brew install stylua

    pip / uv

    pip install git+https://github.com/johnnymorganz/stylua
uv tool install git+https://github.com/johnnymorganz/stylua

    Aftman

    aftman add johnnymorganz/stylua@2.5.2

  7. How StyLua is resolved in the VS Code extension

    main

    The extension uses a specific hierarchy to locate the StyLua binary. It resolves in the following order:

    1. Configuration: If stylua.styluaPath is set in your VS Code settings, that path is used immediately.
    2. PATH: If stylua.searchBinaryInPATH is enabled, the extension searches your system's PATH for a stylua executable. It verifies the binary by running stylua --version.
    3. Bundled: If no configuration is provided and no binary is found on the PATH, the extension falls back to a bundled version, which it may download automatically to its internal storage directory.

  8. FormatNode states

    main

    When determining how to handle a specific code node, StyLua uses the FormatNode enum to categorize its status:

    • Skip: The node is completely ignored, either because formatting is currently disabled via a block comment or because the node has an explicit -- stylua: ignore comment.
    • NotInRange: The node falls outside the user-specified formatting range, but the formatter may still look inside it to find items that are within the range.
    • Normal: The node should be formatted according to the provided configuration.

  9. How StyLua resolves configuration files

    main

    StyLua uses a hierarchical approach to find configuration settings. It searches for a configuration file named stylua.toml or .stylua.toml in the following order:

    1. Explicit Path: If the --config-path flag is provided, StyLua uses that specific file.
    2. Directory Search: StyLua looks in the directory of the file being formatted, then searches upwards through parent directories.
    3. Search Root Behavior:
      • By default, the search stops at the current working directory.
      • If the --search-parent-directories flag is used, StyLua continues searching upwards until it reaches the file system root.
    4. Global Configuration Locations: If no local config is found and --search-parent-directories is enabled, StyLua checks global locations:
      • $XDG_CONFIG_HOME/stylua/stylua.toml or $XDG_CONFIG_HOME/stylua.toml
      • $HOME/.config/stylua/stylua.toml or $HOME/.config/stylua.toml
    5. EditorConfig: If the editorconfig feature is enabled, StyLua can also parse .editorconfig files to derive formatting settings if no StyLua-specific config is found.
    6. Default: If no configuration is found, StyLua falls back to its internal default settings.

  10. Configure the StyLua binary path and version

    main

    The extension attempts to find a StyLua binary using these steps:

    1. If stylua.searchBinaryInPATH is enabled, it looks for a stylua binary on your system's PATH and verifies it with stylua --version.
    2. If no binary is found on the PATH, it falls back to a bundled version downloaded from GitHub releases.

    Manual Configuration

    • Specify a custom path: Use the stylua.styluaPath setting to point directly to a specific binary.
    • Select a specific version: Use the stylua.targetReleaseVersion setting to define which version to download, or use the Stylua: Select Version command.
    • Disable version notifications: To stop receiving notifications about new StyLua versions in the status bar, set stylua.disableVersionCheck to true.

  11. How .styluaignore files affect formatting

    main

    StyLua uses .styluaignore files to determine which files should be skipped during formatting.

    By default, if you explicitly pass a file path to the StyLua CLI (e.g., stylua path/to/file.lua), StyLua will format that file even if it matches a pattern in .styluaignore.

    To force StyLua to respect ignore patterns even for explicitly provided paths, you must use the --respect-ignores flag. When this flag is active, any file matching a pattern in .styluaignore will be skipped, regardless of whether it was passed as a command-line argument.

  12. How StyLua LSP handles configuration and ignore files

    main

    The StyLua LSP follows these rules for configuration and file exclusion:

    1. Configuration Discovery: It searches for stylua.toml in the current working directory or the directory containing the file. If --search-parent-directories is enabled, it will also traverse up the directory tree.
    2. Ignore Files: It respects .styluaignore files. If a file is matched by an ignore pattern, the LSP will return null (no edits) when a formatting request is made for that file.
    3. Editor Formatting Options: The LSP can either use its own internal configuration or respect the formatting options sent by the editor (like tab_size and insert_spaces). This behavior is controlled via the respect_editor_formatting_options setting during the LSP initialize phase.