failwind.nvim - Plugins

# `failwind.nvim`: Plugins *Continuation of [[failwind.nvim - Introduction]] and [[failwind.nvim - Options]]* Here we come to the culmination of all the features of `failwind.nvim` - Declaratively installing and configuring Neovim plugins with CSS. All of the plugins are installed in a separate directory so they are isolated from the rest of the plugins you install (so removing failwind will not load any of the plugins or configuration from failwind). Configuring plugins revolves around adding different selectors to the `plugins {}` tag. Failwind supports several different mechanisms of configuring plugins. # Plugins: Simple In the simplest case, you can just add a plugin and point to the github repo where it is hosted by using a class selector of `repo` and the string value of the repository. This will install tpope's "vim-sleuth" plugin. The plugin requires no configuration or setup, and is automatically loaded. ```neovim {"update":true,"path":"_/code/1724250861251.css","timestamp":1725472561978} <pre> plugins { :repo("tpope/vim-sleuth") {} } </pre> ``` ^1724250861251 On startup, failwind will download, install and add this plugin to your runtimepath. If you remove it from the list of plugins, it will no longer get loaded anymore! # Plugins: `setup` Some plugins have a `require('plugin').setup()` function that should get called to load the plugin. We can use the `setup` property to instruct failwind to call these functions at startup. ```neovim {"update":true,"path":"_/code/1724250884275.css","timestamp":1725472453205} <pre> plugins { :repo("echasnovski/mini.nvim") { setup: "mini.trailspace" "mini.ai"; } } </pre> ``` ^1724250884275 This example is equivalent to: ```neovim {"update":true,"path":"_/code/1724250900115.lua","timestamp":1725472452972} <pre> -- (installed mini.nvim somehow) require("mini.trailspace").setup() require("mini.ai").setup() </pre> ``` ^1724250900115 This makes it very easy to add plugins that have a good default configuration. # Plugins: Custom Setup However, sometimes you want to override the default configuration. Fortunately, setup can also be called as a class selector to declare how failwind should load the plugin. ```neovim {"update":true,"path":"_/code/1724250913708.css","timestamp":1725472452741} <pre> plugins { :repo("lewis6991/gitsigns.nvim") { :setup("gitsigns") { signs { add { text: '+' } change { text: '~' } delete { text: '_' } topdelete { text: '‾' } changedelete { text: '~' } } } } } </pre> ``` ^1724250913708 This example is equivalent to calling this at startup: ```neovim {"update":true,"path":"_/code/1724250930380.lua","timestamp":1725472452509} <pre> -- (install gitsigns somehow) require("gitsigns").setup { signs = { add = { text = "+" }, change = { text = "~" }, delete = { text = "_" }, topdelete = { text = "‾" }, changedelete = { text = "~" }, }, } </pre> ``` ^1724250930380 There are times where you don't want to call `setup()`, but instead want to run arbitrary code after the plugin has been loaded. For that we can use the `config` property (you'll notice here we use a `kebab-cased` name, "vim-cmd-colorscheme", which is translated into "vim.cmd.colorscheme" when called: this is just a fun feature I added since CSS doesn't have namespaced functions. So I just made them). Anyway, this sets the colorscheme to "tokyonight" on loading this plugin. ```neovim {"update":true,"path":"_/code/1724251514281.css","timestamp":1725472452267} <pre> plugins { :repo("folke/tokyonight.nvim") { config: vim-cmd-colorscheme('tokyonight'); } } </pre> ``` ^1724251514281 So it's equivalent to: ```neovim {"update":true,"path":"_/code/17242535451814.lua","timestamp":1725472452027} <pre> -- (somehow install tokyonight) -- After loading the plugin vim.cmd.colorscheme('tokyonight') </pre> ``` ^1724253545181 # Plugins: Advanced Of course, it wouldn't be Neovim without overly complicated keymaps and a litany of custom functions that only I like and will fight to the death about them being OBJECTIVELY BETTER than whatever naming scheme other people come up with. In this example, you will see the use of the `depends` property, which will ensure that other plugins are installed as dependencies. There is another usage of the `setup` property, which calls the default setup function. And after that, you'll see a variety of different options for configuring keymaps related to the plugin - some even using syntax to execute lua that is embedded into the keymap! ```neovim {"update":true,"path":"_/code/17242535451813.css","timestamp":1725472451796} <pre> plugins { :repo("nvim-telescope/telescope.nvim") { depends: "nvim-lua/plenary.nvim"; setup: 'telescope'; keymaps { normal { :key('<leader>sh') { command: "Telescope help_tags"; } :key('<leader>sk') { command: "Telescope keymaps"; } :key('<leader>sf') { command: "Telescope find_files"; } :key('<leader>ss') { command: "Telescope builtin"; } :key('<leader>sw') { command: "Telescope grep_string"; } :key('<leader>sg') { command: "Telescope live_grep"; } :key('<leader>sd') { command: "Telescope diagnostics"; } :key('<leader>sr') { command: "Telescope resume"; } :key('<leader>s.') { command: "Telescope oldfiles"; } :key('<leader><leader>') { command: "Telescope buffers"; } :key('s/') { desc: "Search in Open Files"; @call require('telescope.builtin').live_grep { grep_open_files: true; prompt_title: "Live Grep in Open Files"; } } :key('<leader>sn') { desc: "Search Neovim Files"; @call require('telescope.builtin').find_files { prompt_title: "Search Neovim DotFiles"; cwd: vim-fn-stdpath("config"); } } } } } } </pre> ``` ^1724253545181 # Plugins: Groups The only thing different about this last plugin configuration is that instead of the selector describing a particular repository that is being configured, it creates a `group` that is being configured. The main benefit of this is to create a logical name and grouping for a related set of plugins where there is not one "parent" plugin - for example for LSP. The below example sets up the LSP, installation and basic configuration for Lua and Golang out of the box. Keymaps could be added as well to provide all of the regular LSP goodies that are included in a Neovim distribution or starter kit. ```neovim {"update":true,"path":"_/code/17242535451802.css","timestamp":1725472451569} <pre> plugins { lsp { depends: "neovim/nvim-lspconfig" "williamboman/mason.nvim" "williamboman/mason-lspconfig.nvim" "WhoIsSethDaniel/mason-tool-installer.nvim"; setup: "mason" "mason-lspconfig"; :setup("mason-tool-installer") { automatic_installation: true; ensure_installed: ["lua_ls", "gopls"]; } :config { @call require('mason-lspconfig').setup_handlers { lua_ls: lua('require("lspconfig").lua_ls.setup {}'); gopls: lua('require("lspconfig").gopls.setup {}'); } } } } </pre> ``` ^1724253545180 # Plugins: Import It's 2024 now and managing your own plugin configuration and installation is a chore. With failwind.nvim, we can outsource that management to other people (just like tailwind outsources knowing things and learning css to other people). Using css's builtin `@import` syntax and feature queries, we can instruct failwind to: 1. Download the corresponding repo 2. Find the `init.css` from that repo 3. Parse and load the filtered configuration 4. Use that configuration in your own file. So, when we have something like this: ```neovim {"update":true,"path":"_/code/17242535451791.css","timestamp":1725472451340} <pre> @import url("tjdevries/kickstart.css") plugins; </pre> ``` ^1724253545179 This will take all of the plugins in my `kickstart.css` project and include them into my own configuration! But, we can take this one step further. We can filter the plugins that we want to install by using a feature query. So if we pass a list of plugin and/or group names, we can filter out what items we want to install. ```neovim {"update":true,"path":"_/code/17242535451780.css","timestamp":1725472451123} <pre> @import url("tjdevries/kickstart.css") (plugins: [ "lewis6991/gitsigns.nvim" lsp ]); </pre> ``` ^1724253545178 In this example, we install **ONLY** `gitsigns` and the `lsp` configuration (all associated plugins) from my `kickstart.css` project. # Conclusion There's a few more goodies I'll write about for failwind, but I hope you enjoyed reading about plugin configuration and importing other plugin configuration directly into your own config with failwind. Feel free to drop a follow or reach out with any questions! :)