DEV Community: Diego Frattini

Configuring Neovim with development experience in mind

Diego Frattini — Tue, 03 Jan 2023 10:30:16 +0000

A long time passed since I wrote of my approach of migrating from VSCode to Neovim. That article saw its birth just after an intense first round of wrestling with the terminal editor as a developer with a traditional IDE experience.
I was happy with the results. In fact, I managed to code with reasonable speed in a matter of weeks.

The early achievements left me excited, with many ideas for improvements and countless doubts on how to achieve many of them. That must be the general feeling of most Vim/Neovim new adopters.

Today I am sharing how I continued to enhance my configuration, grouping related functionalities into domains and organising my modules in a tree structure. I am also showcasing a few non trivial custom integrations targeted at improving the experience of using the terminal editor.

Solving the right problem

While developing a (Neo)Vim configuration, one experiences being end user and solution provider at the same time. It is not by chance that most vim plugins used to be pieces of user configuration refined over time, later on made independent and packaged for sharing.

It made sense then to lay a list of personal pain points and expectations to face as challenges to solve while extending my configuration. The list came on the back of the configuration first pass, with all its ~~horrific~~ pragmatic compromises.

Challenge #1: Code split

When it comes to code organisation most configurations I have seen do one of the following: they either put everything inside one big file or they split into multiple files having one of them dedicated to global options, one to plugins management, one to each plugin’s setup, one to keyboard mappings, and so on.

Having a single file allows to manage everything in one place, although it soon becomes uneasy to maintain. Dividing seems to make sense, but the mentioned split criteria forces to make changes in multiple locations whenever a tweak is needed.

I opted instead for organising my setup by grouping functionalities based on their coupling, following an approach inspired by DDD.
Correlated plugins, their declarations, setup and associated customisations ends up arranged in their own module, separated from other ones containing unrelated sets of configurations.
Here is the Editor module as example:

-- ~/.config/nvim/lua/editor/init.lua

local Module = require("_shared.module")

---@class Editor
local Editor = {}

Editor.modules = {
    "editor.syntax",
    "editor.language",
    "editor.completion",
    "editor.spelling",
}

Editor.plugins = {
    -- Comments
    "b3nj5m1n/kommentary",
    -- Autoclosing pair of chars
    "windwp/nvim-autopairs",
    -- Parentheses, brackets, quotes, XML tags
    "tpope/vim-surround",
    -- Change case and handles variants of a word
    "tpope/vim-abolish",
    -- additional operator targets
    "wellle/targets.vim",
    -- Highlighting command ranges
    { "winston0410/range-highlight.nvim", requires = "winston0410/cmd-parser.nvim" },
}

function Editor:setup()
    -- Kommentary
    vim.g.kommentary_create_default_mappings = false

    -- Range highlight
    require("range-highlight").setup()

    -- ...
end

return Module:new(Editor)

Defining the correct number of domains and their boundaries is one of the most challenging aspects of similar architecture choices.
At the time of writing, modules organisation looks like the following:

config
├─ editor
│  ├─ completion
│  ├─ language
│  ├─ spelling
│  ├─ syntax
├─ finder
│  ├─ list
│  ├─ picker
├─ interface
│  ├─ tab
│  ├─ theme
│  ├─ window
├─ project
│  ├─ git
│  ├─ github
│  ├─ tree
├─ terminal
├─ _shared

I am not following DDD principles strictly and I am instead breaking several of them. For example domain consumers reach directly for subdomains.
There is a hierarchical relationship among domains and subdomains: all modules are logically tied together in a tree structure thanks to the Module class every configuration node is an instance of:

-- ~/.config/nvim/lua/_shared/module.lua

---Represents a configuration module
---@class Module
local Module = {}

--- Module specific plugins
Module.plugins = {}

--- Module submodules
Module.modules = {}

--- Module specific configurations
Module.setup = function() end

--- Initializes the module
function Module:init()
    self:setup()

    for _, child_module_name in ipairs(self.modules) do
        local child_module = require(child_module_name)

        child_module:init()
    end
end

---@generic M
---@type fun(module: M): Module | M
function Module:new(m)
        setmetatable(m, self)
        self.__index = self

        -- Sourcing submodules
        for _, child_module_name in ipairs(m.modules) do
            require(child_module_name)
        end

        return m
end

return Module

When the configuration gets sourced, the root config module is initialised, initialising in turn all other modules in recursive fashion:

-- ~/.config/nvim/init.lua

local config = require("config")

config:init()

The tree logical organisation also solves one of the major challenges presented by placing plugins declarations in different files.
Packer.nvim prescribes all plugins to be registered in a single startup call. I couldn’t therefore let modules register them independently.
Instead, I leveraged tree search to gather all plugins declarations in a single place:

-- ~/.config/nvim/lua/_shared/module.lua

---Represents a configuration module
---@class Module
local Module = {}

-- ...

--- Returns a flat list of all the plugins used by the module and by its children
function Module:list_plugins()
    local plugins = vim.deepcopy(self.plugins)
    local child_modules = self.modules

    for _, child_module_name in ipairs(child_modules) do
        local child_module = require(child_module_name)
        local child_module_plugins = child_module:list_plugins()

        for _, child_module_plugin in ipairs(child_module_plugins) do
            table.insert(plugins, child_module_plugin)
        end
    end

    return plugins
end

return Module

The root config module takes care of installation procedures and feeding the list of plugins to packer by overriding the init method:

-- ~/.config/nvim/lua/config.lua

local Module = require("_shared.module")

local installed = nil
local install_path = vim.fn.stdpath("data") .. "/site/pack/packer/start/packer.nvim"
local config_files = vim.fn.expand("~", false) .. "/.config/nvim/**/*"

local Config = {}

Config.plugins = {
    "wbthomason/packer.nvim",
}

Config.modules = {
    "interface",
    "project",
    "editor",
    "finder",
    "terminal",
}

function Config:init()
    -- Checking packer install location
    installed = vim.fn.empty(vim.fn.glob(install_path)) == 0

    -- Cloning packer in place if it is not found
    if not installed then
        print("Installing plugins...")
        vim.fn.execute("!git clone https://github.com/wbthomason/packer.nvim " .. install_path)
        vim.cmd([[packadd packer.nvim]])
    end

    -- Registering plugins to use
    require("packer").startup(function(use)
        use(self:list_plugins())
    end)

    -- Installing plugins
    if not installed then
        local group = vim.api.nvim_create_augroup("OnPackerSyncComplete", { clear = true, once = true })
        vim.api.nvim_create_autocmd("User", {
            group = group,
            pattern = "PackerComplete",
            callback = function()
                self:init()
                vim.cmd("packloadall!")
            end,
        })

        require("packer").sync()
        return
    end

    self:setup()

    for _, child_module_name in ipairs(self.modules) do
        local child_module = require(child_module_name)

        child_module:init()
    end
end

function Config:setup()
    -- ...
end

return Module:new(Config)

When Neovim is launched, the root module detects whether it is needed to perform a full installation by checking for the presence of packer. That happens before any other module is initialised, avoiding errors given by uninstalled dependencies. Thanks to the PackerComplete command exposed by the plugin manager, it is possible to delay the actual initialisation until plugins are installed and ready. Nice.

The final goal remains to have related plugins and associated setup in a single file. When any customisation tweaks will be needed, all relevant code will be found in the same location.
It results trivial to add, remove and refactor config modules as their content is mostly independent from other modules.

Challenge #2: Shared settings

Modules split and tree structure deal with plugins and related customisations.
Neovim options represent instead a shared concern for all configuration domains. Nonetheless, options are expected to be found and managed in a single location because many of them interacts with one another.
The same can be stated for user keymaps as it is generally needed to avoid overlapping and to find consistent patterns to facilitate mnemonics.

It is possible to centralise global options and keymaps through a dedicated interface. Even selected plugin options benefit from being managed there, allowing to tweak them without changing associated modules:

-- ~/.config/nvim/lua/settings.lua

local Settings = {}

Settings._globals = {
    -- Asking for confirmation instead of just failing certain commands
    confirm = true,
    -- Incremental live completion (note: this is now a default on master)
    inccommand = "nosplit",
    -- Set highlight on search
    hlsearch = true,
    -- Highlighting the cursor line
    cul = true,
    -- Avoid rerendering during macros, registers etc
    lazyredraw = true,

    -- ...

}

function Settings.globals(globals)
    if not globals then
        return Settings._globals
    end

    Settings._globals = vim.tbl_extend("force", Settings._globals, globals)

    for option_name, option_value in pairs(Settings._globals) do
        vim.opt[option_name] = option_value
    end

    return Settings._globals
end

Settings._keymaps = {
    leader = " ",
    -- Buffers navigation
    ["buffer.next"] = "<A-Tab>",
    ["buffer.prev"] = "<A-S-Tab>",
    -- Write only if changed
    ["buffer.save"] = "<leader>w",
    -- Write all
    ["buffer.save.all"] = "<leader>W",
    -- Quit (or close window)
    ["buffer.close"] = "<leader>q",
    -- Delete buffer
    ["buffer.close.delete"] = "<leader>Q",

    -- ...

}

Settings.keymaps = validator.f.arguments({
    validator.f.optional(validator.f.shape({
        leader = validator.f.optional("string"),
    })),
}) .. function(keymaps)
    if not keymaps then
        return Settings._keymaps
    end

    Settings._keymaps = vim.tbl_extend("force", Settings._keymaps, keymaps)

    return Settings._keymaps
end

Settings._options = {
    ["language.parsers"] = {},
    ["language.servers"] = {},
    ["theme.colorscheme"] = "nightfox",
    ["theme.component_separator"] = "│",
    ["theme.section_separator"] = "█",
    ["terminal.jobs"] = {},
}

Settings.options = function(options)
    if not options then
        return Settings._options
    end

    Settings._options = vim.tbl_extend("force", Settings._options, options)

    return Settings._options
end

return setmetatable(Settings, {
    __call = function(self, settings)
        local globals = settings.globals or {}
        local keymaps = settings.keymaps or {}
        local options = settings.options or {}

        self.globals(globals)
        self.keymaps(keymaps)
        self.options(options)

        return self
    end,
})

Configuration modules consume globals, keymaps and plugin options by using provided getters. The idea is to decouple customisation logics from raw values:

-- ~/.config/nvim/lua/editor/init.lua

local Module = require("_shared.module")
local settings = require("settings")

---@class Editor
local Editor = {}

-- ...

function Editor:setup()
    -- ...

    local keymaps = settings.keymaps()

    vim.keymap.set(
        "n",
        keymaps["buffer.next"],
        ":bnext<Cr>",
        { noremap = true, silent = true }
    )

    -- ...
end

return Module:new(Editor)

Shared settings are handled independently and initialised just before modules are.
The existence of a dedicated interface enables injecting overrides from external sources, effectively simulating the behaviour of software that allow to manage user preferences using a dedicated user settings file:

-- ~/.config/nvim/init.lua

local settings = require("settings")
local config = require("config")

-- User settings
local custom_settings_file = vim.fn.stdpath("config") .. "/settings.lua"
local custom_settings = vim.fn.filereadable(custom_settings_file) == 1 and dofile(custom_settings_file) or {}
settings(custom_settings)

-- Initialisation
config:init()

I didn’t yet dig deeper into all possibilities unlocked by the use of a settings file.
An idea that comes to mind is to give the chance of overriding values depending on the working directory path, allowing to define different setups for different projects.

Challenge #3: Validation

Lua is a powerful little language. Despite its simplicity, it provides all building blocks required to replicate advanced constructs.

The only feature I miss dearly when coding in Lua is a type system.
Knowing whether a specific method was called with an incorrect signature before appreciating the code blowing up at runtime is quite valuable. Also, the process of debugging without the support of a type system can be sometimes more than frustrating.

In dynamically typed language contexts the situation can be mitigated by configuring a language server which will provide diagnostics either by inferring types from code or parsing purposely written annotations.
Besides, runtime validation is often applied by developers when needed. Neovim specifically offers vim.validate api for validation.

/usr/local/Cellar/neovim/0.8.1/share/nvim/runtime/doc/lua.txt

validate({opt})
    Validates a parameter specification (types and values).

    Usage example:  

      function user.new(name, age, hobbies)
        vim.validate{
          name={name, 'string'},
          age={age, 'number'},
          hobbies={hobbies, 'table'},
        }
        ...
      end

There are two main factors making my eye twitch when validation is applied this way.
Firstly, that is an imperative approach and details of arguments validation ends up mixed with logics consuming those.
Secondly, the signature of vim.validate is inconsistent and can be called in different ways:

/usr/local/Cellar/neovim/0.8.1/share/nvim/runtime/doc/lua.txt

Parameters:  
      • {opt}  (table) Names of parameters to validate. Each key is a
               parameter name; each value is a tuple in one of these forms:
               1. (arg_value, type_name, optional)
                  • arg_value: argument value
                  • type_name: string|table type name, one of: ("table", "t",
                    "string", "s", "number", "n", "boolean", "b", "function",
                    "f", "nil", "thread", "userdata") or list of them.
                  • optional: (optional) boolean, if true, `nil` is valid

               2. (arg_value, fn, msg)
                  • arg_value: argument value
                  • fn: any function accepting one argument, returns true if
                    and only if the argument is valid. Can optionally return
                    an additional informative error message as the second
                    returned value.
                  • msg: (optional) error string if validation fails

Whilst this was possibly done to offer more flexibility, I preferred instead to create my own wrapper around it with the purpose of unifying validation apis and providing a declarative interface to consumers.

Decorators are a good candidate for applying arguments validation without modifying decorated functions. Lua doesn’t offer decorators natively, but it is relatively easy to implement them using metamethods. I decided to use __concat , which visually results in concatenating arguments validations to their target functions:

-- ~/.config/nvim/lua/_shared/key.lua

local validator = require("_shared.validator")

local Key = {}

-- ...

--- Replaces terminal codes and keycodes (<CR>, <Esc>, ...) in a string with the internal representation.
---@type fun(keys: string)
Key.to_term_code = validator.f.arguments({ "string" })
    .. function(keys)
        return vim.api.nvim_replace_termcodes(keys, true, true, true)
    end

--- Characters in keys are queued for processing as if they
--- come from a mapping or were typed by the user.
--- Replaces terminal codes and keycodes (<CR>, <Esc>, ...) in a
--- string with the internal representation.
---@type fun(keys: string, mode?: string): number
Key.input = validator.f.arguments({ "string", validator.f.optional(validator.f.pattern("^[mntix!]+$")) })
    .. function(keys, input_mode)
        local mode = input_mode or "n" -- Noremap mode by default
        return Key.feed(Key.to_term_code(keys), mode)
    end

return Key

Validations are defined in schema-inspired fashion by using validator.f.arguments, which in turn accepts a list of validators mapped to function arguments by order.
Decorating a function with validation ultimately means to wrap it in another function which will intercepts its arguments performing assertions on them, either throwing an exception or eventually calling the decorated function with valid arguments:

-- ~/.config/nvim/lua/_shared/validator.lua

local Validator = {}

Validator.f = {

    -- ...

    ---@class ArgumentsValidator
    ---@operator concat:function
    ---@operator call:function

    ---Generates a function decorator which validates arguments passed to the decorated function
    ---@param arguments_validators table validators to use for function arguments
    ---@param error_message? string error message thrown
    ---@return ArgumentsValidator
    arguments = function(arguments_validators, error_message)
        error_message = error_message or "Arguments validation error: %s"
        local validate_arguments = Validator.f.list(arguments_validators)

        return setmetatable({
            decorate = function(func)
                return function(...)
                    local valid, validation_error = validate_arguments({ ... })

                    if not valid then
                        error(string.format(error_message, validation_error))
                    end

                    return func(...)
                end
            end,
        }, {
            __call = function(self, ...)
                return self.decorate(...)
            end,
            __concat = function(self, ...)
                return self.decorate(...)
            end,
        })
    end,
}

return Validator

Validators are generated at function definition and triggered at function call. They can be composed as needed to achieve the level of validation detail required.
Besides, they can still be used imperatively for code reusability purposes or when the situation calls for it:

local validator = require("_shared.validator")

---@alias TreeNode
--- | {name: string} # Node representing the parent directory
--- | {absolute_path: string, fs_stat: { type: string } } # Node

local validate_node = validator.f.any_of({
    -- Directory or file
    validator.f.shape({
        absolute_path = "string",
        fs_stat = validator.f.shape({
            type = "string",
        }),
    }),
    -- Upper directory
    validator.f.shape({
        name = "string",
    }),
})

-- Using the validator directly
local node = { absolute_path = "/node/path", fs_stat = { type = "file" } }
validate_node(node)

---@class Project.Tree
local Tree = {}

---@type fun(self: Project.Tree, node: TreeNode)
Tree.search_in_node = validator.f.arguments({ validator.f.equal(Tree), validate_node })
    .. function(_, node)
        -- ...
    end

---@type fun(self: Project.Tree, node: TreeNode)
Tree.tree_actions_menu = validator.f.arguments({ validator.f.equal(Tree), validate_node })
    .. function(self, node)
        -- ...
    end

Validation logics is now completely decoupled from function bodies. Validation rules are defined in a declarative manner, hiding technical details behind a readable interface.

In all honesty, I started abstracting a few utilities to make vim.validate more consistent and, like it often happens, I ended up writing a small library. I am happy with it though as it currently covers any validation needs I may have and it has proven straightforward to extend.

Internal validation behaviours are a bit complex to be fully described in this article. The full code is found here, though.

Challenge #4: Experience

Neovim saw dramatic usability improvements if compared to its father Vim, although it suffers from the same lack of discoverability which makes long time users still unaware of all functionalities available to them.
That justifies the popularity of plugins like which-key, which displays a popup with possible key bindings completing a started command.

I never got around to integrate which-key in my configuration, but I longed nonetheless for having access to contextual actions without the need to remember them all.
Many software provide similar helpful capabilities by using dropdown menus so I decided to try and use telescope to build a customisable menu picker, which I could reuse whenever needed:

-- ~/.config/nvim/lua/finder/picker.lua

local Module = require("_shared.module")
local fn = require("_shared.fn")
local validator = require("_shared.validator")

---@class picker
local Picker = {}

-- ...

---@type fun(self: Picker, menu: { [number]: string, on_select: function }, options: { prompt_title: string } | nil)
Picker.menu = validator.f.arguments({
    validator.f.equal(Picker),
    validator.f.shape({
        validator.f.list({ "string", validator.f.optional("string") }),
        on_select = "function",
    }),
    validator.f.optional(validator.f.shape({
        prompt_title = "string",
    })),
})
    .. function(_, menu, options)
        options = options or {}

        local entry_display = require("telescope.pickers.entry_display")
        local displayer = entry_display.create({
            separator = " ",
            items = {
                -- calculating the max width needed for the first column
                fn.ireduce(menu, function(item, result)
                    item.width = math.max(item.width, #result[1])
                    return item
                end, { width = 10 }),
                { remaining = true },
            },
        })
        local make_display = function(entry)
            return displayer({
                entry.value[1],
                { entry.value[2] or "", "Comment" },
            })
        end
        local entry_maker = function(menu_item)
            return {
                value = menu_item,
                ordinal = menu_item[1],
                display = make_display,
            }
        end

        local finder = require("telescope.finders").new_table({
            results = fn.imap(menu, function(menu_item)
                return menu_item
            end),
            entry_maker = entry_maker,
        })
        local sorter = require("telescope.sorters").get_generic_fuzzy_sorter()
        local default_options = {
            finder = finder,
            sorter = sorter,
            attach_mappings = function(prompt_buffer_number)
                local actions = require("telescope.actions")
                local state = require("telescope.actions.state")
                -- On select item
                actions.select_default:replace(function()
                    menu.on_select({ buffer = prompt_buffer_number, state = state, actions = actions })
                end)
                -- Disabling any kind of multiple selection
                actions.add_selection:replace(function() end)
                actions.remove_selection:replace(function() end)
                actions.toggle_selection:replace(function() end)
                actions.select_all:replace(function() end)
                actions.drop_all:replace(function() end)
                actions.toggle_all:replace(function() end)

                return true
            end,
        }

        require("telescope.pickers").new(options, default_options):find()
    end

---@type fun(self: Picker, menu: { [number]: string, on_select: function }, options: { prompt_title: string } | nil)
function Picker:context_menu(menu, options)
    local theme = require("telescope.themes").get_cursor()
    options = vim.tbl_extend("force", theme, options or {})

    return Picker:menu(menu, options)
end

return Module:new(Picker)

The signature shared by menu and context_menu methods abstracts away the picker’s underlying requirements, allowing to pass a list of menu items alongside a callback triggered on selection.
Besides information necessary to the picker display, extra data can be attached to entries. That comes in handy when handling item selection:

-- ~/.config/nvim/lua/project/tree.lua

local Module = require("_shared.module")
local key = require("_shared.key")
local validator = require("_shared.validator")
local fn = require("_shared.fn")
local settings = require("settings")

---@class Project.Tree
local Tree = {}

-- ...

function Tree:setup()
    require("nvim-tree").setup({
        -- ...

        on_attach = function(tree_buffer)
            local actions = self:actions()
            local mappings = fn.imap(actions, function(action)
                return { action.keymap, action.handler, buffer = tree_buffer }
            end)

            key.nmap(unpack(mappings))

            key.nmap({
                keymaps["dropdown.open"],
                require("nvim-tree.utils").inject_node(fn.bind(self.tree_actions_menu, self)),
                buffer = tree_buffer
            })
        end,
    })
end

function Tree:actions()
    local keymaps = settings.keymaps()

    return {
        {
            name = "Edit in vertical split",
            keymap = keymaps["project.tree.node.open.vertical"],
            handler = require("nvim-tree.api").node.open.vertical,
        },
        {
            name = "Edit in horizontal split",
            keymap = keymaps["project.tree.node.open.horizontal"],
            handler = require("nvim-tree.api").node.open.horizontal,
        },
        {
            name = "Edit in tab",
            keymap = keymaps["project.tree.node.open.tab"],
            handler = require("nvim-tree.api").node.open.tab,
        },

        -- ...
    }
end

---@type fun(self: Project.Tree, node: TreeNode)
Tree.tree_actions_menu = validator.f.arguments({ validator.f.equal(Tree), validate_node })
    .. function(self, node)
        local actions = self:actions()
        local menu = vim.tbl_extend(
            "error",
            fn.imap(actions, function(action)
                return { action.name, action.keymap, handler = action.handler }
            end),
            {
                on_select = function(context_menu)
                    local selection = context_menu.state.get_selected_entry()
                    context_menu.actions.close(context_menu.buffer)
                    selection.value.handler(node)
                end,
            }
        )
        local options = { prompt_title = node.name }

        require("finder.picker"):context_menu(menu, options)
    end

return Module:new(Tree)

The code example above showcases opening a context menu containing nvim-tree actions:

By the way, nvim-tree.utils inject_node is a higher order function which passes data of the node found at cursor position into the received function, making keymap callbacks potentially capable of dynamically change the menu depending on it.
Likewise, it can be used to add behaviours not initially present among the tree explorer default actions:

-- ~/.config/nvim/lua/project/tree.lua

local Module = require("_shared.module")
local key = require("_shared.key")
local validator = require("_shared.validator")
local fn = require("_shared.fn")
local settings = require("settings")

---@class Project.Tree
local Tree = {}

-- ...

function Tree:setup()
    require("nvim-tree").setup({
        -- ...

        on_attach = function(tree_buffer)
            local actions = self:actions()
            local mappings = fn.imap(actions, function(action)
                return { action.keymap, action.handler, buffer = tree_buffer }
            end)

            key.nmap(unpack(mappings))

            key.nmap({
                keymaps["dropdown.open"],
                require("nvim-tree.utils").inject_node(fn.bind(self.tree_actions_menu, self)),
                buffer = tree_buffer
            })
        end,
    })
end

function Tree:actions()
    local keymaps = settings.keymaps()

    return {
        -- ...

        {
            name = "Search node contents",
            keymap = keymaps["project.tree.search.node.content"],
            handler = require("nvim-tree.utils").inject_node(fn.bind(self.search_in_node, self)),
        },

        -- ...
    }
end

---@type fun(self: Project.Tree, node: TreeNode)
Tree.search_in_node = validator.f.arguments({ validator.f.equal(Tree), validate_node })
    .. function(_, node)
        -- when the selected node is the one pointing at the parent directory, absolute_path will not be present
        if not node.absolute_path then
            return require("finder.picker"):text()
        end

        -- live_grep in highlighted directory
        if node.fs_stat.type == "directory" then
            return require("finder.picker"):text(node.absolute_path)
        end

        -- open file and current_buffer_fuzzy_find
        if node.fs_stat.type == "file" then
            require("nvim-tree.actions.node.open-file").fn("edit_in_place", node.absolute_path)
            return require("finder.picker"):buffer_text()
        end
    end

return Module:new(Tree)

In such manner it is trivial to integrate between nvim-tree and telescope built-in pickers. The example uses one keymap only, but the handler acts differently based on the currently highlighted node. If the cursor is on a directory the live grep picker will be displayed to search within the folder. If the cursor is on a file instead its buffer will be opened and the current buffer fuzzy find picker displayed.
A gif is worth a thousand words:

Grouping related functionalities together helps making them more accessible at the cost of adding just a few keystrokes.

After gloating for a while looking at the completed context menu implementation, it stroked me that the same idea could be scaled to menus themselves.
I could gloat even more if I managed to provide an interface to create “tabbed” collections of pickers and navigate them reusing the same keymaps used to navigate buffers:

-- ~/.config/nvim/lua/finder/picker.lua

local Module = require("_shared.module")
local key = require("_shared.key")
local fn = require("_shared.fn")
local validator = require("_shared.validator")
local settings = require("settings")

---@class Finder.Picker.Tab
---@field prompt_title string
---@field find function

---@class Finder.Picker.Tabs
local Tabs = {}

---@type fun(self: Finder.Picker.Tabs, tabs: Finder.Picker.Tab[]): Finder.Picker.Tabs
Tabs.new = validator.f.arguments({
    -- This would be cool but it is not possible because builtin pickers are launched directly
    -- validator.f.list({ validator.f.instance_of(require("telescope.pickers")._Picker) }),
    validator.f.equal(Tabs),
    validator.f.list({ validator.f.shape({ prompt_title = "string", find = "function" }) }),
})
    .. function(self, tabs)
        tabs._current = 1

        setmetatable(tabs, self)
        self.__index = self

        return tabs
    end

function Tabs:_options()
    return {
        prompt_title = self:_prompt_title(),
        attach_mappings = fn.bind(self._attach_mappings, self),
    }
end

-- NOTE: this is a lot of code just to calculate a fancy prompt title
-- TODO: refactor?
function Tabs:_prompt_title()
    local globals = settings.globals()
    local current_picker_title = "[ " .. self[self._current].prompt_title .. " ]"

    -- Creating a table containing all titles making up for the left half of the title
    -- starting from the left half of the current picker title and looping backward
    local i_left = self._current - 1
    local prev_picker_titles = { string.sub(current_picker_title, 1, math.floor(#current_picker_title / 2)) }
    repeat
        if i_left < 1 then
            i_left = #self
        else
            table.insert(prev_picker_titles, 1, self[i_left].prompt_title)
            i_left = i_left - 1
        end
    until i_left == self._current

    -- Creating a table containing all titles making up for the right half of the title
    -- starting from the right half of the current picker title and looping onward
    local i_right = self._current + 1
    local next_picker_titles = {
        string.sub(current_picker_title, (math.floor(#current_picker_title / 2)) + 1, #current_picker_title),
    }
    repeat
        if i_right > #self then
            i_right = 1
        else
            table.insert(next_picker_titles, self[i_right].prompt_title)
            i_right = i_right + 1
        end
    until i_right == self._current

    -- Merging left and right, capping at 40 chars length
    local prompt_title_left = string.reverse(
        string.sub(string.reverse(table.concat(prev_picker_titles, " ")), 1, (20 - #globals.listchars.precedes))
    )
    local prompt_title_right = string.sub(table.concat(next_picker_titles, " "), 1, (20 - #globals.listchars.extends))
    local prompt_title = globals.listchars.precedes
        .. prompt_title_left
        .. prompt_title_right
        .. globals.listchars.extends

    return prompt_title
end

---@param buffer number
---@return boolean
function Tabs:_attach_mappings(buffer)
    local keymaps = settings.keymaps()

    key.imap({
        keymaps["buffer.next"],
        fn.bind(self.next, self),
        buffer = buffer,
    }, {
        keymaps["buffer.prev"],
        fn.bind(self.prev, self),
        buffer = buffer,
    })

    return true
end

function Tabs:prev()
    self._current = self._current <= 1 and #self or self._current - 1

    local options = self:_options()
    local picker = self[self._current]

    return picker.find(options)
end

function Tabs:next()
    self._current = self._current >= #self and 1 or self._current + 1

    local options = self:_options()
    local picker = self[self._current]

    return picker.find(options)
end

function Tabs:find()
    local options = self:_options()
    local picker = self[self._current]

    return picker.find(options)
end

---@class Picker
local Picker = {}

-- ...

function Picker:setup()
    local keymaps = settings.keymaps()

    key.nmap(
        -- ...

        { keymaps["find.help"], fn.bind(self.help, self) },

        -- ...
    )
end

function Picker:tabs(pickers)
    return Tabs:new(pickers)
end

function Picker:help()
    return self:tabs({
        { prompt_title = "Help", find = require("telescope.builtin").help_tags },
        { prompt_title = "Commands", find = require("telescope.builtin").commands },
        { prompt_title = "Options", find = require("telescope.builtin").vim_options },
        { prompt_title = "Autocommands", find = require("telescope.builtin").autocommands },
        { prompt_title = "Keymaps", find = require("telescope.builtin").keymaps },
        { prompt_title = "Filetypes", find = require("telescope.builtin").filetypes },
        { prompt_title = "Highlights", find = require("telescope.builtin").highlights },
    }):find()
end

-- ...

return Module:new(Picker)

Similarly to what happens with custom menus, the picker tabs functionality is exposed by the finder.picker configuration module api so that other domains can consume it to build their own picker collections. Menus and tabs are compatible and one could create tabbed pickers out of custom menus.
The only argument required is the list of pickers, each described by prompt_title and find catering for picker’s title and launch function:

I am overall satisfied with menus and tabbed pickers solutions as they are proving useful to my development flows. Thanks to the heavy lifting done by telescope, they ease from the need of brute-force-memorising all commands by making them more accessible.

Conclusions

My main goals with Neovim revolve around making my configuration easier to maintain, scalable and having a more friendly experience while using it.

The code samples presented in this article were simplified, trying to focus them on the topics discussed. The full code is found in my dotfiles repository. Like any (Neo)Vim configuration that is permanently WIP.

Please keep in mind that I possibly spent more time than I should have on the improvements described. I am indeed treating my config almost like it was a commercial project and not my own customisation. It is likely that some of the examples will look over-engineered for the purpose of building a personal setup.
In any case, I am having plenty of fun learning about both Neovim and Lua.

If a bit of self-promotion is allowed, I maintain Sherpa as an open source project dedicated to free learning.
I collect and organise educative resources with the goal of helping people learn about dev topics, giving an alternative to paid subscriptions platforms. I also created a Neovim and Lua learning paths there! Check them out if you are interested.

A pragmatic approach to migrating from VSCode to Neovim

Diego Frattini — Mon, 14 Feb 2022 10:04:24 +0000

Photo by Dries Augustyns on Unsplash

I made Neovim my main code editor, migrating from VSCode.

I knew moving away from an “ordinary” code editor would be challenging. That is why, instead of going full cold turkey, I opted for easing the process by modelling my initial configuration around behaviours I am already comfortable with.

In this article, I am going to describe the approach I followed, explaining why I preferred a solution over another. I will provide links to content I was supported by, so that any interested reader will be able to explore further.
Although I will mainly compare to VSCode, it should be possible to adopt a similar pipeline moving from any other editor.

It is possible to find related configuration files tracked in my dotfiles repository.
Also, I gathered the most helpful resources I found in the Neovim learning path. You will find at that location most of the resources I am going to reference, and also additional ones I could not fit in this article.

Of course, why

For developers, people who spend most of their daytime reading and writing code, the editor of choice is obviously important.
It often happens that is so important one has to adhere to a faction:

[...] IDEs were starting to become very sophisticated starting around the year 2000 [...] and [editor camp] people saw those sophisticated features and said “Nah, I don’t need that”. And you were being forced to choose. Do you want to be a text editor person or an IDE person? My point is that is a false dichotomy.

Keyes, J. M. (2019, November). We can have nice things [Talk]. VimConf 2019, Akihabara Tokyo, Japan. https://youtu.be/Bt-vmPC_-Ho

The line between editors and IDE is blurred these days as editors can often offer IDE-like functionalities just by installing few plugins.
Recently, VSCode in particular became quite popular for many web development needs.

I too am a VSCode user. I am a happy VSCode user, too.
Apart from the much disputed memory hunger typical of Electron applications and the existence of grey areas behind its licensing choices, VSCode is a great software I cannot really complain about. It provides nearly everything I need to support my day-to-day development activities, without leaving the editor.

Nearly everything. Without leaving the editor. That is where my problems with VSCode start. I am providing an example explain better.

I installed a neat Microsoft extension, Docker, which

[...] makes it easy to build, manage, and deploy containerized applications from Visual Studio Code. It also provides one-click debugging of Node.js, Python, and .NET Core inside a container.

Docker for Visual Studio Code. (2022). Visual Studio Marketplace. https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker

Docker is powerful and complex. Thanks to the extension, it is effectively possible to consume Docker commands inside VSCode by interacting with its UI. That allows utilising Docker without having to deal with the complexity of its CLI.
That also implies, assuming one uses the extension as primary mean to interact with Docker, the understanding of it will be limited by what the plugin offers and shaped by its pre-packaged mental model.

Although simplifying development flows is essential to achieve results without needing to focus on every cog of the engine, I want to learn more, get closer to the metal and grow conscious about what happens behind the curtains of a well refined interface. I need to use tools that nudge me into learning new things.

Besides, a good part of my daily development activities lives in the terminal already, so moving to a terminal-based editor feels like closing the gap.

Getting started

Learning Vim is not difficult per se. It is challenging indeed, if one tries to approach it like they would with any other text editor. One has to learn thinking in Vim to make sense of its commands interface. Memorising by brute force a bunch of keyboard combinations won’t work very well. At least, it didn’t work for me.

When I started investigating around how to migrate to Vim I didn’t know where to start. I was never a command line aficionado and my knowledge of the editor was limited to typing :q! to quit it.
Thus, I started tackling the challenge in discovery mode, trying to gather many resources to find which one would better suit my necessities.
Since the first readings, I was already absolutely fascinated by the concept of coding by describing the desired end result, rather than mechanically executing the steps needed to achieve it.
I think the same principle applies when comparing imperative and declaritive programming styles. Who am I to tell, though.

Was I ready to start using and learning Vim at this point? Yes. Also no.
Before starting the journey, I needed to clear one final doubt: would I use Vim or Neovim?
A bit more reading pushed me towards Neovim.
I am happy I made that decision, although I confess I was not fully understanding the difference at the time.

The plan

There is a well known quote attributed to W. Edwards Deming which goes like:

If you can't describe what you are doing as a process, you don't know what you're doing.

Whilst going through more tutorials and articles, it was becoming clear customising Vim to one’s needs is among the strongest selling points of the editor, and can become a never ending task.
I needed to formalise a definition of done which could give me boundaries.
Therefore, I compiled a list of functionalities I believed to be indispensable, based on what in VSCode I valued the most. I would follow the list and flibber-jibber the frammistan to achieve similar results following “the vim way”.

Be aware I am cheating: at the very beginning the list was just a flat, chaotic collection of items. Only after I started getting my hands dirty it was possible to wrap my head around how features interact and can be grouped together.
Anyway, here is the list:

Interface

Theming
Status bar with contextual information
Project explorer

Editor

Syntax highlighting
Indentation guides
Split windows
Tags autocompletion
Brackets and quotes autocompletion
Commenting and uncommenting lines
Multiple cursors editing
Text case change

IntelliSense

Code completion
Code navigation
Code diagnostics
Code linting and formatting

Search

Search and replace in a file
Search and replace in a project
Search and replace in a folder
Files fuzzy find
Commands fuzzy find

Git integration

Git status
Git diff
Conflicts merge helper
Hunks diff
GitHub PRs integration

Extras

Multiple projects management
Todos management
Terminal integration

The list was long and comprehensive of core VSCode functionalities alongside others, available through extensions.

I decided to aim for a MVP result, to quickly start using Neovim as my primary editor, test and improve the setup against real-world development scenarios.
That means I had to leave some cool ideas behind, waiting for a more convenient time to have fun with them.

Dirty hands

Vim doesn’t immediately surface many of the functionalities one expects to be slapped in the face with when launching any modern editor.

Vim is incredibly powerful out of the box, but it doesn't truly shine until you take some time to customize it for your particular work, habits, and fingers.

Losh, S. (2013). Preface / Learn Vimscript the Hard Way. Learn Vimscript the Hard Way. https://learnvimscriptthehardway.stevelosh.com/preface.html

I already mentioned I chose to use NeoVim over Vim without precisely knowing why, other than the fact it advertises itself to be a refactor of Vim improving its extensibility and usability while remaining compatible with most of Vim ecosystem, which I took as a win-win situation.

Only when I started customising it, I understood I made a good choice for once. Neovim can be configured using Lua, which I found myself comfortable with. I stumbled upon several good tutorials, but “Everything you need to know to configure neovim using lua” and “Getting started using Lua in Neovim” were lifesavers.

By easing the learning curve of getting acquainted to a new programming language, I could focus on structuring the configuration itself, rather than fighting against an averse syntax.
I split and organised my setup into modules exposing sets of related functionalities.
Grouping features based on their relative coupling, makes it easier to maintain them, as connected ones end up living close in the filesystem. All modules ended up behaving in a predictable way by exposing a common interface.

Do you see what I did there? My preferred approach to structuring applications is not the point. What matters is I was able to reuse my development skills to design my setup.
The feeling of not just learning to use an editor, but creating my own personal coding tool by extending Neovim was thrilling to me.
It was almost like building a kallax and using a gnabbas to store my fåtalig and my favourite eftertänka.

Interface

I began writing Lua code from something simple, figuring the addition of a few colour schemes could represent a quick-win to make the terminal’s brutalist appearance a little more approachable.

Neovim supports any Vim theme, but I focussed on exclusive extensions where sensible, like it is in the case of colour schemes.
In fact, an acclaimed addition to the 0.5 Neovim release was the support for tree-sitter, which provides advanced code parsing functionalities. That means it offers, among other mouth-filling wizardries, support for better syntax highlighting. The nvim-treesitter repository lists supported languages and compatible themes.
I found shaunsingh/nord.nvim, avarasu/onedark.nvim, sainnhe/edge and rose-pine/neovim simply irresistible.

As statusline, I chose Lualine because I was blown away by its performance when compared to other similar plugins, as advertised in its repository documentation. Or maybe because it was supported and documented by the colour schemes I had just installed. Who knows.

Vim comes out of the box with a filesystem explorer, a plugin called Netrw. It happens not to be extremely appreciated by Vim users, so I installed nvim-tree.
The plugin felt instantly familiar, because it behaves similarly to what I was already used to.
Still, I was not convinced by it. It made things somehow stiffer when compared to the otherwise unconstricted feeling of interacting with files in Vim. I couldn’t explain exactly what was out of place, until I read Oil and vinegar - split windows and the project drawer.
It was too late, though. I decided to move on and leave the replanning of my approach to projects navigation, and the reviewing of my life choices for a later stage.

Editor

I was practicing with Neovim itself to edit my configuration. I was struggling.
The editor looked better, but was lacking most utilities I would usually take for granted. I needed to make it easier on me to write code.

Plugins.

Indent-blankline to draw indentation guides, nvim-autopairs to automatically complete pairs of brackets and quotes (I didn’t know I couldn’t live without it), nvim-ts-autotag to autocomplete pairs of tags as well, targets.vim to target what is inside or outside the mentioned pairs and vim-surround to manage all those pairs with few keystrokes.
Kommentary to comment and uncomment lines of code, nvim-cursorline to help locate where the cursor is and nvim-colorizer because I am cheeky.
Vim-abolish is definitely an interesting one. I decided to install it because of its case coercion capabilities, but it can do much more than that.

No more plugins, please.

Among my self-imposed non-functional requirements there was using few extensions as possible, to keep things tidy and minimise clashes among them.
I was therefore happy to read about the several abstractions used by Vim to represent a file, realising no extension was needed to work on multiple files at the same time.
In fact, that is an area where Vim is way more structured than other editors.

I dropped instead the idea of multiple cursors editing.
On one side that doesn’t feel very Vim-ish, and on the other side there are multiple native alternatives to achieve similar results. If I ever wanted that functionality at any cost, there would be options nonetheless.

Code completion

I quite like the Microsoft term “IntelliSense”. It gives an instinctual feeling of what the term means, despite referring to a set of complex and interrelated technical features.

As I saw my editing experience improving, I got even more excited and tried to throw in code completion, too.
For the record, Vim supports autocompletion, without the need for any configuration or plugin. The thing is, as some other of its core features, Vim’s autocompletion options are granular and powerful, but rough like a pile of rocks right out of the quarry.
Besides, Neovim introduced built-in support for LSP, with the possibility of using the editor as a client to communicate with language servers and obtain context aware suggestions, autocompletion and diagnostics. IntelliSense, as friends call it.

However, LSP requires some work to be properly setup. More than I was willing to spend whilst still trying to understand how all the pieces of the puzzle fit together.
That’s why I opted for installing coc.nvim instead, with the idea of saving on the efforts needed to reach my MVP goal.
The plugin follows very closely VSCode ways of functioning. One can count on a decent amount of extensions extending the extension, many being themselves ports of VSCode plugins. Last but not least, I was able to find plenty of documentation to set everything up.

I could quickly set things up in a familiar way and see appearing nice code diagnostics and hints. This win felt bittersweet, though.
There are some aspects of the unfortunately named extension I find confusing.
Mostly, I am bothered by COC and its environment trying to push for too many different functionalities under the same flag. Besides language completions, one can find a calculator, integration with git and GitHub gists, custom lists, preview of markdown files, a custom search implementation and more.

I was tempted by some of those features, but determined to avoid creating a big ball of mud.
I cherry-picked (almost) only code completion related COC functionalities, isolating them in their own module, and delegated to other modules the burden of dealing with separated concerns.
I would deliberate later on a possible migration to the Neovim LSP client.

Search

Software engineers often like to think that the job is to write shiny new code.
I think recruiters know that. I couldn’t explain otherwise the number of

I am getting in touch with you because we are looking for superstar developers, willing to work with cutting edge technologies on an exciting greenfield project.

in the mail inbox, as opposed to the lack of

I am getting in touch with you because we are looking for experienced engineers to help us maintain a 10-year-old web application.

It is known, software engineers spend a relevant amount of time tweaking pre-existent codebases rather than creating from scratch.
That could easily be a reason why search and replace functionalities can be valuable, allowing developers find a needle in a haystack.

Vim is rather powerful when it comes to find and replace. While investigating around a good way to translate my workflows, I was once more surprised by realising how far one could go by just relying on its core.

I couldn’t resist however, and eventually installed an extension.
Telescope is a fuzzy finder offering filter, sort and preview capabilities. It is getting a lot of attention in the Neovim community because it is flexible to the point of allowing for the creation of customised finders.
As it comes with plenty of preconfigured pickers catering for my most of my needs, it seemed sensible to include it.

On a side note, I was not surprised instead to discover flamboyant solutions to the challenge.

Git integration

Dealing with version control systems falls in a category of procedures I am willing compromise on in exchange for simplification.
For example, using a GUI client gives me visibility over the global state of the repository at any time, making my life easier when I need to perform non trivial operations. It also forces me to take distance from the code editor, adopting in regard an agnostic point if view whilst thinking about branches, conflicts, diffs and whatnot.
I make use of just a few of the available VSCode VCS integrations.

On those premises, I investigated for ways to improve using git inside Vim, with a pinch of plugins.
Vim-fugitive felt almost an obligated choice because of its huge popularity. It offers Vim commands wrapping CLI ones, improving their ergonomics. I well liked the simple effectiveness of the idea.
I installed Gitsigns.nvim to have visual hints of changes applied to the current buffer, while also being able to diff and undo them, if needed.
Finally, I added to the pile octo.nvim, for a more integrated experience working with GitHub.

Although my needs were already covered, I found neogit and diffview.nvim nonetheless interesting and decided make note of them for a later thorough integration.

Extras

By the time I got to evaluate feasible solutions for the “Extra” requirements category, I had walked a long way and learned plenty.
Still, I was unsure whether the awareness of having just scratched the surface was fuelling either a sense of bubbling excitement or profound despair in me.

Anyhow, I started clearing the last requirements standing by installing telescope-project.nvim and todo-comments.nvim. They were a convenient choice, as both extend the already mentioned Telescope plugin.
Seamless terminal integration was possibly the feature I was looking for the most. As I hoped, Neovim offers transparent terminal emulation out of the box, making to open a terminal buffer feel like a first class operation.

Settings synchronisation

Was that the end of the journey? Yes. Also no.
I purposely avoided talking about a central piece of the puzzle, that is synchronising on multiple machines to reuse the setup I bled so much to put together.
I decided discuss it at the end because the challenge has less to do with Neovim that it has to do with managing dotfiles in general. This is where the choice of moving to a different tool started to nudge me out of my comfort zone, pushing me into doing something I never felt the urge for. No shame.

Among numerous feasible approaches, I eventually decided to give a try to storing my configuration as a bare repository.
I was already using Homebrew to manage system packages and it can conveniently take also care of GUI applications. I chose then just to add some custom implementation to have it maintain a dependencies file.
Zsh extensions are instead dealt with as git submodules.
I will sooner or later look into oh-my-zsh, to understand whether I could find a reason for it to exist in my setup.

Conclusions

I appreciate compromises.
Although they are often perceived as unsatisfying decisions, they can also be a way to work out situations difficult to solve otherwise.
If I abruptly adopted Neovim by changing all my coding habits at once, I would probably have failed and would have gone back to my comfort zone.
Instead, I can cautiously state I am successfully using Neovim for most of my coding activities, fully aware that there is still a lot for me to discover about it.
In fact, I ended up compiling a list of todos and ideas that is possibly three times longer than the one I started with.

Among all the plugins I installed, there are several I plan to replace with simple customisations on top of built-in functionalities. I will probably keep only extensions that feel more integrated with Neovim’s core behaviours. I am more a purist than an exobrain, after all.

On a negative side, if one could say that, I am noticing Vim commands are beginning to feel more natural and sensible than my old ways of editing text. Sometimes I surprise myself typing :w to save the current state of a Notion document.
As much as one would love to use Vim superpowers in any editor, they will need to come to terms with modal editing being rarely found outside of (Neo)Vim. Without the use of workarounds and dedicated extensions, that is.

To recap, I talked about moving from an editor to another, planning the migration as an incremental process and adopting strategic choices to make the transition less taxing.
A similar approach could be applied to many situations and is not exclusive to technology contexts, though.
I collected the best resources I found in the Neovim learning path, both as personal reference and as a resource for anyone interested in taking on a similar journey. It is possible to find at that URL all the links I shared in this article and more.
There are other learning paths as well. Be sure to check them out, maybe you will find something interesting.

The Learning Path

Diego Frattini — Tue, 14 Sep 2021 06:43:44 +0000

Cover image by Jannes Glas on Unsplash

TL;DR

I created a website hosting learning paths.

I started building it because of a professional need, then I realised it could be useful to other people, too.
All resources are free as they are selected among tens of gratis videos, tutorials, books found on the web.

If that sounded useful to anybody, they could find it here: https://the-learning-path.vercel.app.

Not TL;DR

I am a self taught developer. I always was.
I know I am not the only one. I know that because of statistics:

Statistically, around 65-70% of developers considered themselves as a self-taught developer and the number is growing rapidly.

Madhur Gupta, and Sagar Kapoor. “7 Best Learning Methods for Self Taught Developers.” GeeksforGeeks, 7 July 2021, www.geeksforgeeks.org/7-best-learning-methods-for-self-taught-developers

I also know that because of personal experience. Among all the engineers I worked with, I could count many coming from rather diverse educational paths: designers, architects, philosophers, mathematicians and even a professionally trained musician who taught me how much music and coding have in common.

Both music and programming can be and are often self taught. People who are self taught are generally pretty successful as they have one of the most important traits: self motivation.

NanoDano. “Similarities Between Music and Programming.” DevDungeon, 5 July 2019, www.devdungeon.com/content/similarities-between-music-and-programming

At the start of my career as a developer, self motivation was driven by curiosity. I wanted to know everything about how software things worked and I believed I would eventually reach my goal because persons conceived those things. I was a person no less. Great reasoning.

I have to admit that was not my only drive, though. Competition played a big role too, as I couldn't stand knowing less than many of my colleagues about something I found so fascinating.

Ego issues aside, it wasn't easy for me to build a mental model of software behaviours and an understanding of engineering practices, without counting on solid fundamentals.
Free learning resources were present but scattered in the wild web, not differently than what still happens Today.
Thankfully I could always rely on several websites helping me out with tutorials and explanations. Some of them are still alive, some others tragically ceased to exist at some point in time.

Css-tricks as it was on November 1st 2012 (https://web.archive.org/web/20121101231755/https://css-tricks.com). I still refer to this website to find examples and inspiration.

Despite the challenges, I managed to find my way through. I can Today call myself a software engineer with no shame and I transitioned to roles with leadership responsibilities.

That transition comes with its own set of complications. As an example, one needs to realise their actions are no longer relevant as individual contributions while commitment around processes and collaboration become more important. This topic alone could give birth to a collection of articles but, since that has been done already and it doesn't spark joy when I think about it, I am not planning to put down any of those.

What I find compelling instead, is learning new things. What my role gives me, is the chance of helping my team to learn new things as well.
I recently tried to do exactly that, but politics got in the way. The short version of the story is I wanted to make use of some paid platform's learning paths to build a shared knowledge base in the team. That unfortunately wasn't an option.

That meant going back to my primal source of learning: free quality resources found on the web. That also meant facing again old challenges, like finding the right content among hundreds, understanding what to start from or what to progress with or figuring out how the unorganised pieces of knowledge fit together.

To try solving those issues once and for all, I decided to create The learning path, where I collected some good videos, readings, books, examples, exercises and cheatsheets I could find. All of them are free.
The resources are categorised by topic and ordered by complexity level, from basic to advanced concepts.
The paths are not a collection of everything. They represent instead an opinionated selection of items which could work nicely together.

"The React learning path" page. React training resources are among the first I collected due to the need of levelling the team knowledge about the library.

The final aim is to provide a valid alternative to similar paid offers, which I always suggest to have a look at anyway.

The deployed website at the time of this writing is the MVP.
I am planning to enrich and refine resources collections, add more features and sections and include more paths.
If this project manages to help anyone learning something, I will see it as a success.
For the time being, I am happy as it is proving useful to me and my team.

Last but not least: a huge thanks to Salvatore Tedde, who supported me in the conception phases of the project and contributed to the website design. He too is a self taught developer and a continuous learner, so I was sure he would be interested and help me with this.