Developer Tools (yalms.dev)

Developer Tools
Overview
Setup
Configuration
- Plugin Configuration
Usage
API Reference

Developer Tools

The yalms.dev module provides developer-focused utilities including persistent scratchpads and hot-reloading for Neovim plugins. It watches plugin source files and re-runs setup() on file changes, plus provides persistent scratch buffers for testing.

Prerequisites

Snacks.nvim must be installed.

Overview

Persistent scratch buffers per plugin for testing code
File watching for automatic plugin reloading (calls plugin.setup(old_opts) on change)
Snacks picker integration for scratch selection
Run plugin code directly from scratch buffer

Setup

Initialize via YALMS or directly:

require('yalms').setup({
  dev = {
    dir = vim.fn.stdpath("data"),
    plugins = {
      myplugin = {
        path = vim.fn.stdpath("config") .. "/lua/myplugin",
        opts = { some_option = true },
      },
    },
  },
})

Or directly:

-- Enable with defaults (dir = stdpath("data"), no plugins configured)
require('yalms.dev').setup(true)

-- Full configuration
require('yalms.dev').setup({
  dir = vim.fn.stdpath("data"),
  plugins = {
    myplugin = {
      path = vim.fn.stdpath("config") .. "/lua/myplugin",
    },
  },
})

Passing true to setup() uses the default configuration — useful when you want to register plugins later with watch().

Configuration

Option	Type	Default	Description
`dir`	string	`vim.fn.stdpath("data")`	Base directory for scratches
`plugins`	table	`{}`	Map of plugin name to `DevPluginOpts`
`scope`	table	`{ cwd = true }`	Scope for scratch storage (passed to Snacks picker)

Plugin Configuration

Each plugin entry:

plugins = {
  myplugin = {
    path = "/path/to/plugin",      -- required: plugin directory to watch
    opts = { ... },           -- optional: passed to plugin.setup() on file change
  }
}

Usage

Scratch Buffers

When a plugin is configured, a persistent scratch buffer is created at <dir>/<myplugin>.lua.

Open the scratch picker:

:Snacks picker dev_scratches

Key	Action
Right	Enter plugin's scratches
Left	Go back to plugins
Alt-a	Add new scratch
Alt-r	Remove scratch
Alt-e	Rename scratch

When you select a scratch from the picker (with Right or Enter), the picker closes automatically and the scratch buffer opens. This keeps your window layout clean — you do not need to close the picker manually.

Opening Scratches

local dev = require('yalms.dev').get()

-- Open default scratch for a plugin
dev:open("myplugin")

-- Open specific scratch
dev:open_scratch("myplugin", "my_scratch")

File Watching

When plugin source files change, the plugin is torn down and re-setup with stored options:

-- On file change, the manager reloads the plugin and calls setup() with stored options

Manual Watch Control

-- Stop watching a plugin
dev:unwatch("myplugin")

-- Start watching manually
dev:watch("myplugin", { path = "...", opts = { ... } })

API Reference

Method	Description
`get()`	Get the DevManager instance
`setup(opts)`	Initialize dev module
`teardown()`	Stop all watchers and cleanup
`list()`	Get all configured plugins
`open(name)`	Open default scratch for plugin
`open_scratch(name, scratch)`	Open named scratch
`add_scratch(name, scratch)`	Add new scratch
`remove_scratch(name, scratch)`	Remove scratch
`rename_scratch(name, old, new)`	Rename scratch
`list_scratches(name)`	List all scratches for plugin
`watch(name, config)`	Start watching a plugin
`unwatch(name)`	Stop watching a plugin

Full dev API