f42f958c24
## Problem The plugin requires users to install Node.js and the `live-server` npm package globally. This is a heavyweight external dependency for what amounts to a simple local dev-server workflow, and it creates friction for users who don't otherwise need Node.js. ## Solution Replace the npm shell-out with a pure-Lua HTTP server built on `vim.uv` (libuv bindings), eliminating all external dependencies. The new server supports static file serving, SSE-based live reload, CSS hot-swap without full page reload, directory listings, and recursive file watching with configurable debounce. Minimum Neovim version is bumped to 0.10 for `vim.uv` and `vim.ui.open`. The old `args`-based config is automatically migrated with a deprecation warning. Closes #28.
152 lines
6.2 KiB
Text
152 lines
6.2 KiB
Text
*live-server.txt* Live reload for web development
|
|
|
|
Author: Barrett Ruth <https://barrettruth.com>
|
|
Homepage: <https://github.com/barrettruth/live-server.nvim>
|
|
|
|
===============================================================================
|
|
INTRODUCTION *live-server.nvim*
|
|
|
|
live-server.nvim automatically reloads HTML, CSS, and JavaScript files in the
|
|
browser via a local development server. No external dependencies required —
|
|
the server runs entirely in Lua using Neovim's built-in libuv bindings.
|
|
|
|
===============================================================================
|
|
REQUIREMENTS *live-server-requirements*
|
|
|
|
- Neovim >= 0.10
|
|
|
|
===============================================================================
|
|
CONFIGURATION *live-server-config*
|
|
|
|
*vim.g.live_server*
|
|
Configure via `vim.g.live_server` before the plugin loads: >lua
|
|
|
|
vim.g.live_server = {
|
|
port = 8080,
|
|
browser = false,
|
|
}
|
|
<
|
|
*live_server.Config*
|
|
Fields: ~
|
|
|
|
{port} (`integer?`) Port for the HTTP server. Default: `5500`
|
|
{browser} (`boolean?`) Auto-open browser on start. Default: `true`
|
|
{debounce} (`integer?`) Debounce interval in ms for file changes.
|
|
Default: `120`
|
|
{ignore} (`string[]?`) Lua patterns for file paths to ignore when
|
|
watching for changes. Default: `{}`
|
|
{css_inject} (`boolean?`) Hot-swap CSS without full page reload.
|
|
Default: `true`
|
|
{debug} (`boolean?`) Log each step of the hot-reload chain via
|
|
|vim.notify()| at DEBUG level. Default: `false`
|
|
|
|
===============================================================================
|
|
COMMANDS *live-server-commands*
|
|
|
|
*:LiveServerStart*
|
|
:LiveServerStart [dir] Start the live server. If `dir` is provided, the
|
|
server starts in the specified directory. Otherwise,
|
|
uses the directory of the current file.
|
|
|
|
*:LiveServerStop*
|
|
:LiveServerStop [dir] Stop the live server. If `dir` is provided, stops
|
|
the server running in the specified directory.
|
|
|
|
*:LiveServerToggle*
|
|
:LiveServerToggle [dir] Toggle the live server on or off. If `dir` is
|
|
provided, toggles the server in that directory.
|
|
|
|
===============================================================================
|
|
MAPPINGS *live-server-mappings*
|
|
|
|
*<Plug>(live-server-start)*
|
|
<Plug>(live-server-start) Start the live server. Equivalent to
|
|
|:LiveServerStart| with no arguments.
|
|
|
|
*<Plug>(live-server-stop)*
|
|
<Plug>(live-server-stop) Stop the live server. Equivalent to
|
|
|:LiveServerStop| with no arguments.
|
|
|
|
*<Plug>(live-server-toggle)*
|
|
<Plug>(live-server-toggle) Toggle the live server. Equivalent to
|
|
|:LiveServerToggle| with no arguments.
|
|
|
|
Example configuration: >lua
|
|
vim.keymap.set('n', '<leader>ls', '<Plug>(live-server-start)')
|
|
vim.keymap.set('n', '<leader>lx', '<Plug>(live-server-stop)')
|
|
vim.keymap.set('n', '<leader>lt', '<Plug>(live-server-toggle)')
|
|
<
|
|
|
|
===============================================================================
|
|
API *live-server-api*
|
|
|
|
All functions accept an optional `dir` parameter. When omitted, the directory
|
|
of the current file is used.
|
|
|
|
live_server.start({dir}) *live_server.start()*
|
|
Start the live server in the specified directory.
|
|
|
|
Parameters: ~
|
|
{dir} (`string?`) Directory to serve
|
|
|
|
live_server.stop({dir}) *live_server.stop()*
|
|
Stop the live server running in the specified directory.
|
|
|
|
Parameters: ~
|
|
{dir} (`string?`) Directory of running server
|
|
|
|
live_server.toggle({dir}) *live_server.toggle()*
|
|
Toggle the live server on or off.
|
|
|
|
Parameters: ~
|
|
{dir} (`string?`) Directory to toggle
|
|
|
|
live_server.setup({user_config}) *live_server.setup()*
|
|
Deprecated: Use |vim.g.live_server| instead.
|
|
|
|
Parameters: ~
|
|
{user_config} (|live_server.Config|?) Configuration table
|
|
|
|
===============================================================================
|
|
EXAMPLES *live-server-examples*
|
|
|
|
Start server in project root: >vim
|
|
|
|
:LiveServerStart ~/projects/my-website
|
|
<
|
|
Lua keybinding to toggle server: >lua
|
|
|
|
vim.keymap.set('n', '<leader>ls', '<Plug>(live-server-toggle)')
|
|
<
|
|
Configuration with custom port and no auto-open: >lua
|
|
|
|
vim.g.live_server = {
|
|
port = 3000,
|
|
browser = false,
|
|
}
|
|
<
|
|
Ignore node_modules and dotfiles: >lua
|
|
|
|
vim.g.live_server = {
|
|
ignore = { 'node_modules', '^%.' },
|
|
}
|
|
<
|
|
===============================================================================
|
|
KNOWN LIMITATIONS *live-server-limitations*
|
|
|
|
No Recursive File Watching on Linux ~
|
|
*live-server-linux-recursive*
|
|
libuv's `uv_fs_event` only supports recursive directory watching on macOS
|
|
(FSEvents) and Windows (ReadDirectoryChangesW). On Linux, the `recursive`
|
|
flag is silently accepted but ignored because inotify does not support it
|
|
natively. Only files directly in the served root directory trigger
|
|
hot-reload; files in subdirectories (e.g. `css/style.css`) will not be
|
|
detected.
|
|
|
|
See https://github.com/libuv/libuv/issues/1778
|
|
|
|
Enable `debug` in |live-server-config| to verify whether `fs_event`
|
|
callbacks fire for a given file change.
|
|
|
|
-------------------------------------------------------------------------------
|
|
vim:tw=78:ft=help:norl:
|