DEV Community: Munif Tanjim

Neovim - Project Local Config with exrc.nvim

Munif Tanjim — Thu, 11 Aug 2022 16:47:00 +0000

Neovim is awesome and I love it!

Why? You might ask. The answer is rather simple.

It's awesome because I love it.

Now that we agree on that, let's focus on the topic... Project Local Config.

Why is Project Local Config?

Usually your Neovim configuration lives in a single location: ~/.config/nvim. And most of the times, that's all you need. But what if you need to change some config only for a specific project? Maybe you want to set a different theme when you're working on that project... or maybe tweak the behavior of the LSP server for that specific project.

That's why you need project local config for Neovim. It can be done in multiple ways and I'm gonna list them all.

Modify your Neovim config file

This is the most straight-forward way of doing it. In your Neovim config file, you need check the current working directory and set the config based on that:

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

local cwd = vim.fn.getcwd(-1, -1)

if cwd == '/path/to/project-a' then
  -- config for project-a
elseif cwd = '/path/to/project-b' then
  -- config for project-b
end

Pros:

Safe. It's your own config.
Supports Lua config file.

Cons:

Config can't be tracked with the project using git.
Hardcoded paths are machine dependent.

If you're okay with this approach, you can stop here. But do continue if you want something better.

Built-in Option: `exrc`

This is the built-in 'exrc' option. If enabled, Neovim will search for the following files in the current directory:

.nvimrc
.exrc

And use the first one it finds.

Enabling it is as simple as adding this in your Neovim config:

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

vim.o.exrc = true

Pros:

Built-in feature.
Config can be tracked with the project using git.

Cons:

Deprecated (check :help 'exrc').
Security risk. Config is run blindly.
No support for Lua config file.

If you end up going with this approach, you should also enable the 'secure' option. That will reduce the security risk of 'exrc' option a bit.

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

vim.o.secure = true

But if you want one better, the next one is for you.

Plugin: `exrc.nvim`

It's the plugin that I wrote to make 'exrc' great again. It does everything the built-in 'exrc' option does and then some more... and does all that safely.

You install it like any other plugin, using your plugin manager of choice. And the set it up like this:

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

vim.o.exrc = false

require("exrc").setup({
  files = {
    ".nvimrc.lua",
    ".nvimrc",
    ".exrc.lua",
    ".exrc",
  },
})

Now you can add local config file for your project:

--[[ /path/to/project-a ]]

print("This is awesome!")

And then, the first time you open this project, you'll be greeted with this prompt:

If you allow it, it will run the config file and remember your choice. If the config file changes, it will show the prompt again for you to review the updated content.

Pros:

Secure. Config is run only after you review and allow it.
Config can be tracked with the project using git.
Supports Lua config file.

Cons:

Once you use it, you can't do without it.

Project Local LSP Settings with exrc.nvim

Now, let's see how you can use exrc.nvim to modify LSP settings for a specific project.

Let's define a helper function in Neovim's config directory:

--[[ ~/.config/nvim/lua/config/lsp/custom.lua ]]

local mod = {}

---@param server_name string
---@param settings_patcher fun(settings: table): table
function mod.patch_lsp_settings(server_name, settings_patcher)
  local function patch_settings(client)
    client.config.settings = settings_patcher(client.config.settings)
    client.notify("workspace/didChangeConfiguration", {
      settings = client.config.settings,
    })
  end

  local clients = vim.lsp.get_active_clients({ name = server_name })
  if #clients > 0 then
    patch_settings(clients[1])
    return
  end

  vim.api.nvim_create_autocmd("LspAttach", {
    callback = function(args)
      local client = vim.lsp.get_client_by_id(args.data.client_id)
      if client.name == server_name then
        patch_settings(client)
        return true
      end
    end,
  })
end

return mod

Now let's say you want to setup Lua Language Server (a.k.a sumneko_lua) for Hammerspoon config directory. For that, make sure:

LSP is set up correctly in your Neovim config.
EmmyLua spoon is installed and loaded in your Hammerspoon config.

Next, create your project local config file in the Hammerspoon config directory (i.e. ~/.config/hammerspoon):

--[[ ~/.config/hammerspoon/.nvimrc.lua ]]

require("config.lsp.custom").patch_lsp_settings("sumneko_lua", function(settings)
  settings.Lua.diagnostics.globals = { "hs", "spoon" }

  settings.Lua.workspace.library = {}

  local hammerspoon_emmpylua_annotations = vim.fn.expand("~/.config/hammerspoon/Spoons/EmmyLua.spoon/annotations")
  if vim.fn.isdirectory(hammerspoon_emmpylua_annotations) == 1 then
    table.insert(settings.Lua.workspace.library, hammerspoon_emmpylua_annotations)
  end

  return settings
end)

If you open Neovim in that directory now, exrc.nvim will run the .nvimrc.lua file to change the settings for sumneko_lua to work with Hammerspoon's APIs. 🤘🏼

That's it for today!

You can find all the snippets here Gist: Neovim - Project Local Config with exrc.nvim.

And the plugin repository here: MunifTanjim/exrc.nvim.

Have a great day! 😃

Originally published at muniftanjim.dev on August 11, 2022.

Setup Neovim on Github Actions

Munif Tanjim — Sat, 04 Dec 2021 15:36:29 +0000

My Workflow

I maintain some Neovim plugins and wanted to setup automated tests for those using GitHub Actions. First thing you need for testing Neovim plugin is "neovim" itself.

So I wrote this small GitHub Action with only 30-ish lines of code. It takes a Neovim release tag, downloads the archive and sets it up for you. It works on Linux and macOS.

This would be useful to anybody who maintains Neovim plugins.

Submission Category:

Maintainer Must-Haves

Yaml File or Link to Code

MunifTanjim / setup-neovim-action

🚀 Setup Neovim on Github Actions.

Setup Neovim - GitHub Action

Setup Neovim on Github Actions.

Usage

See action.yml

Basic (stable release):

steps:
  - uses: actions/checkout@v2
  - uses: MunifTanjim/setup-neovim-action@v1
  - run: |
      nvim --version

Specific Tag:

steps:
  - uses: actions/checkout@v2
  - uses: MunifTanjim/setup-neovim-action@v1
    with:
      tag: nightly
  - run: |
      nvim --version

For list of available tags, check: https://github.com/neovim/neovim/tags

Compile from Source:

steps:
  - uses: actions/checkout@v2
  - uses: MunifTanjim/setup-neovim-action@v1
    with:
      tag: source
  - run: |
      nvim --version

License

Licensed under the MIT License. Check the LICENSE file for details.

View on GitHub

Additional Resources / Info

If you want to see it in action, check:

Setup Lua/LuaJIT/LuaRocks in GitHub Actions workflow without any hassle 🌛

Munif Tanjim — Sat, 27 Nov 2021 17:17:43 +0000

My Workflow

Recently I've been dabbling with Lua, mostly tinkering with my Neovim configuration and building some plugins for it. But I've been thinking about doing some other projects using Lua too. So I built this tool called Luver for removing the some obstacles I faced going that way.

And it occured to me that it would be a pretty handly tool to use with GitHub Actions workflow.

GitHub Action: Setup Lua with Luver

How would it help you?

🌜 You can easily install specific versions of Lua/LuaJIT/LuaRocks for your CI workflow.
🚀 You have install multiple versions of Lua side-by-side and switch between them in your CI workflow. So you can run tests for your Lua library against multiple version of Lua!

Submission Category:

Maintainer Must-Haves

Yaml File or Link to Code

MunifTanjim / luver-action

🌛 Set up your GitHub Actions workflow with specific versions of Lua, LuaJIT, LuaRocks using Luver ❤️

Luver GitHub Action

🌛 Set up your GitHub Actions workflow with specific versions of Lua, LuaJIT, LuaRocks using Luver ❤️

Usage

See action.yml

Basic:

steps:
  - uses: actions/checkout@v2
  - uses: MunifTanjim/luver-action@v1
  - run: |
      luver install lua 5.4.3
      luver use 5.4.3
      luver install luarocks 3.8.0
  - run: |
      luarocks install luacheck

Pre-install versions:

steps:
  - uses: actions/checkout@v2
  - uses: MunifTanjim/luver-action@v1
    with:
      lua_versions: 5.1.5 5.4.3
      luajit_versions: 5.1.5:2.1.0-beta3
      luarocks_versions: 5.1.5:3.7.0 5.4.3:3.8.0
  - run: |
      luver use 5.1.5
      lua -v
      luajit -v
      luarocks --version

Set default lua version:

steps:
  - uses: actions/checkout@v2
  - uses: MunifTanjim/luver-action@v1
    with:
      default: 5.1.5
      lua_versions: 5.1.5 5.4.3
  - run: |
      lua -v

License

Licensed under the MIT License. Check the LICENSE file for details.

View on GitHub

Additional Resources / Info

If you work on Lua projects often, you can also use Luver on your development machine, it is comparable to nvm, pyenv, rbenv etc. If you think a tool like that would help you, check out: MunifTanjim/luver

Performance Optimization - What not to Optimize

Munif Tanjim — Mon, 27 Sep 2021 11:02:37 +0000

No, this is not a well thought-out blog post about software performance optimization and pitfalls that come with it. Rather this is an anecdote. So take it with a pinch of salt, for words and stories can be meaningless if taken out of context.

The other day I was talking to one of my friends and he wanted to run a problem by me that he was trying to solve. It was a problem about performance optimization. Well, duh, what else would it be about? It says "Performance Optimization" right in the title of this post.

He was working with a database system that exposes an API for bulk operations. For example, you could create, delete and update some items with a single request:

{ "create": { "name": "Mr. Nobody", "age": 42 } }
{ "update": { "id": 17, "name": "John Doe" } }
{ "delete": { "id": 27 } }

And he had a large array where each item represents one of these operations. Something like this:

{ "_operation": "create", "name": "Mr. Nobody", "age": 42 }

He said he was struggling to prepare the body for this request. And the table was turned. Now, it was me who was struggling to find the struggle-worthy problem in there. Because regardless of the language being used, the solution would look somewhat like this:

const operations = []

for (const item of items) {
  const operation_name = item._operation
  delete item._operation

  const operation = {}
  operation[operation_name] = item

  operations.push(operation)
}

const requestBody = operations.join('\n')

Before you say something, yes, I know that even a thing so simple as this can feel daunting to somebody who's just starting to learn programming. But that's not the case here. I promise you this is about "Performance Optimization" as it says in the title.

So I told him exactly what I was thinking, "Have you tried looping over the items and create a string representing the desired shape for the request body?"

He said, "Yeah, that works. But I'm trying to optimize it. There are thousands of items and looping over them is not very perfomant."

That got me even more confused, so I asked, "You're trying to optimize out the 'for loop'?! You said it's not very perfomant, compared to what?"

To which he said, "If I have to loop over each item separately, what would even be the point of using the bulk operation API anymore? I might as well call individual API for each item."

Wait, hold up! That doesn't add up! Does it? 🤔

The cost of a network call can't be comparable to the cost of a single iteration of 'for loop' here. A single network call doing bulk operations is definitely gonna be more performant than doing a thousand network calls for those individual operations. Yeah, it definitely doesn't make sense. And as I explained it to him, he understood it completely and agreed with it.

Knowing what not to optimize is important. And how you know that is by measuring it. If you don't know difference between the time it takes to make a network call and going through a loop iteration, you're bound to make silly mistakes.

So before thinking about optimizing stuffs, ask yourself, do you really need to do it? Are you really focusing on the right thing?

And that, my friend, is a reminder for myself and for any of you who sometimes feels tempted to optimize stuffs where it's not needed. There's no point in denying it, we've all been there and we know it. 😂

Originally published at muniftanjim.dev on September 25, 2021.

Neovim - Build UI using nui.nvim

Munif Tanjim — Tue, 20 Jul 2021 09:28:33 +0000

I've been using Neovim almost everyday, for years now. I play around with my config files often and recently been trying out the built-in LSP features that come with Neovim 0.5+.

For my work stuffs I still use coc.nvim and I'm quite used to the nice and simple UIs it provides to interact with the LSP client. So I wanted something similar for the built-in LSP client too.

And I found some excellent projects that provide UIs for LSP. For example:

Surely, I could've used one of them and called it a day. But this blog post wouldn't be here if I did that! 😝

Instead I thought, what if I try to make those UIs myself? So the next logical (🤔) thing was to search for plugin/library for building Neovim UIs quickly. Here's what I found so far:

Most of the Neovim Lua plugins I saw share some version or variant of codes from these two plugins (because all of them are trying to do the same thing). All these duplication of efforts needs to end. But, how?

Initially I thought about contributing to popup.nvim or neovim-ui project. But those projects have different goals than what I had in mind. What I want is to have a high-level API with a lot of sugar for doing repetitive things. Those projects are focused more on low-level stuffs.

So... Alright people let's do this one last time! 🤟

Enter `nui.nvim`

The UI component library for Neovim that I've been working on for the past few weeks.

Features and Goals:

Customizable UI
High-level API to build UI elements
Sugar for doing repetitive things, e.g. autocmd, keymap etc.

It's still in early stage of development, but it's quite usable right now. If you're interested in using it, have ideas, feature requests, want to contribute or just appreciate the project - please do check the GitHub repo MunifTanjim/nui.nvim 😃

Now, it's demo time...

UI for LSP Rename using nui.nvim

Let's try to build the UI for LSP textDocument/rename operation using nui.nvim.

First of all, let's get the identifier name under cursor:

local curr_name = vim.fn.expand("<cword>")

To send request to the LSP server for renaming this identifier, we need the exact position of it. Neovim got us covered:

local params = vim.lsp.util.make_position_params()

Now, what happens when we get the new name for the identifier? Let's write a on_submit callback function that is expected to be called with the new name:

local function on_submit(new_name)
  if not new_name or #new_name == 0 or curr_name == new_name then
    -- do nothing if `new_name` is empty or not changed.
    return
  end

  -- add `newName` property to `params`.
  -- this is needed for making `textDocument/rename` request.
  params.newName = new_name

  -- send the `textDocument/rename` request to LSP server
  vim.lsp.buf_request(0, "textDocument/rename", params, function(_, result, _, _)
    if not result then
      -- do nothing if server returns empty result
      return
    end

    -- the `result` contains all the places we need to update the
    -- name of the identifier. so we apply those edits.
    vim.lsp.util.apply_workspace_edit(result)

    -- after the edits are applied, the files are not saved automatically.
    -- let's remind ourselves to save those...
    local total_files = vim.tbl_count(result.changes)
    print(
      string.format(
        "Changed %s file%s. To save them run ':wa'",
        total_files,
        total_files > 1 and "s" or ""
      )
    )
  end)
end

Now that all those are done, let's focus on creating the UI for getting the new name for the identifier:

local Input = require("nui.input")

local popup_options = {
  -- border for the window
  border = {
    style = "rounded",
    text = {
      top = "[Rename]",
      top_align = "left"
    },
  },
  -- highlight for the window.
  highlight = "Normal:Normal",
  -- place the popup window relative to the
  -- buffer position of the identifier
  relative = {
    type = "buf",
    position = {
      -- this is the same `params` we got earlier
      row = params.position.line,
      col = params.position.character,
    }
  },
  -- position the popup window on the line below identifier
  position = {
    row = 1,
    col = 0,
  },
  -- 25 cells wide, should be enough for most identifier names
  size = {
    width = 25,
    height = 1,
  },
}

local input = Input(popup_options, {
  -- set the default value to current name
  default_value = curr_name,
  -- pass the `on_submit` callback function we wrote earlier
  on_submit = on_submit,
  prompt = "",
})

Believe it or not, the UI is ready. Now we just need to render it:

input:mount()

That's it! The input popup window will show up.

It'll initially be in INSERT mode. You can press Esc to exit INSERT mode or CTRL-c to close the popup window. If you press Enter, the on_submit callback function will be invoked with the input value and the popup window will be closed.

Let's add some additional interactions. If Esc is pressed in NORMAL mode, let's close the popup window:

-- close on <esc> in normal mode
input:map("n", "<esc>", input.input_props.on_close, { noremap = true })

Also close it when the cursor leaves the popup window:

local event = require("nui.utils.autocmd").event

-- close when cursor leaves the buffer
input:on(event.BufLeave, input.input_props.on_close, { once = true })

Now all you need to do is put all these inside a function nui_lsp_rename in a separate file and map your keys to start the renaming.

For example, put the file at ~/.config/nvim/lua/config/nui_lsp.lua:

-- file: ~/.config/nvim/lua/config/nui_lsp.lua

local function nui_lsp_rename()
  -- ... the implementation from above
end

return {
  lsp_rename = nui_lsp_rename,
}

And map your keys in your Neovim config file:

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

-- you probably want to put this inside the `on_attach` callback function 
-- of your lsp server config and use `vim.api.nvim_buf_set_keymap` instead.
vim.api.nvim_set_keymap(
  "n",
  "<Leader>rn",
  "<cmd>lua require('config.nui_lsp').lsp_rename()<CR>",
  { noremap = true, silent = true }
)

You can find the whole snippet here Gist: Neovim LSP Rename with nui.nvim.

That's it for today!

If you have any queries, questions or thoughts on nui.nvim, let's Discuss at GitHub.

Have a great day! 😄

Originally published at muniftanjim.dev on July 18, 2021.

Basic Middleware Pattern in JavaScript

Munif Tanjim — Wed, 07 Oct 2020 10:00:21 +0000

Ever wondered how the middlewares in popular web frameworks, e.g. Express or Koa, work?

In Express, we have the middleware functions with this signature:

const middleare = (req, res, next) => {
  // do stuffs
  next()
}

In Koa, we have this:

const middleware = (ctx, next) => {
  // do stuffs
  next()
}

Basically, you have some objects (req, res for Express or ctx for Koa) and a next() function as the arguments of the middleware function. When next() is called, the next middleware function is invoked. If you modify the argument objects in the current middleware function, the next middleware will received those modified objects. For example:

// Middleware usage in Koa

app.use((ctx, next) => {
  ctx.name = 'Doe'
  next()
})

app.use((ctx, next) => {
  console.log(ctx.name) // will log `Doe`
})

app.use((ctx, next) => {
  // this will not get invoked
})

And if you don't call the next() function, the execution stops there and the next middleware function will not be invoked.

Implementation

So, how do you implement a pattern like that? With 30 lines of JavaScript:

function Pipeline(...middlewares) {
  const stack = middlewares

  const push = (...middlewares) => {
    stack.push(...middlewares)
  }

  const execute = async (context) => {
    let prevIndex = -1

    const runner = async (index) => {
      if (index === prevIndex) {
        throw new Error('next() called multiple times')
      }

      prevIndex = index

      const middleware = stack[index]

      if (middleware) {
        await middleware(context, () => {
          return runner(index + 1)
        })
      }
    }

    await runner(0)
  }

  return { push, execute }
}

This implementation of middleware pattern is almost the same as Koa. If you want to see how Koa does it, check out the source code of koa-compose package.

Usage

Let's see an example of using it:

// create a middleware pipeline
const pipeline = Pipeline(
  // with an initial middleware
  (ctx, next) => {
    console.log(ctx)
    next()
  }
)

// add some more middlewares
pipeline.push(
  (ctx, next) => {
    ctx.value = ctx.value + 21
    next()
  },
  (ctx, next) => {
    ctx.value = ctx.value * 2
    next()
  }
)

// add the terminating middleware
pipeline.push((ctx, next) => {
  console.log(ctx)
  // not calling `next()`
})

// add another one for fun ¯\_(ツ)_/¯
pipeline.push((ctx, next) => {
  console.log('this will not be logged')
})

// execute the pipeline with initial value of `ctx`
pipeline.execute({ value: 0 })

If you run that piece of code, can you guess what the output will be? Yeah, you guessed it right:

{ value: 0 }
{ value: 42 }

By the way, this would absolutely work with async middleware functions too.

TypeScript

Now, how about giving it some TypeScript love?

type Next = () => Promise<void> | void

type Middleware<T> = (context: T, next: Next) => Promise<void> | void

type Pipeline<T> = {
  push: (...middlewares: Middleware<T>[]) => void
  execute: (context: T) => Promise<void>
}

function Pipeline<T>(...middlewares: Middleware<T>[]): Pipeline<T> {
  const stack: Middleware<T>[] = middlewares

  const push: Pipeline<T>['push'] = (...middlewares) => {
    stack.push(...middlewares)
  }

  const execute: Pipeline<T>['execute'] = async (context) => {
    let prevIndex = -1

    const runner = async (index: number): Promise<void> => {
      if (index === prevIndex) {
        throw new Error('next() called multiple times')
      }

      prevIndex = index

      const middleware = stack[index]

      if (middleware) {
        await middleware(context, () => {
          return runner(index + 1)
        })
      }
    }

    await runner(0)
  }

  return { push, execute }
}

With everything being typed, now you can declare the type of the context object for a specific middleware pipeline, like this:

type Context = {
  value: number
}

const pipeline = Pipeline<Context>()

Okay, that's all for now.

Originally published at muniftanjim.dev on October 4, 2020.

DEV Community: Munif Tanjim

Neovim - Project Local Config with exrc.nvim

Why is Project Local Config?

Modify your Neovim config file

Built-in Option: exrc

Plugin: exrc.nvim

Project Local LSP Settings with exrc.nvim

Setup Neovim on Github Actions

My Workflow

Submission Category:

Yaml File or Link to Code

MunifTanjim / setup-neovim-action

🚀 Setup Neovim on Github Actions.

Setup Neovim - GitHub Action

Usage

License

Additional Resources / Info

Setup Lua/LuaJIT/LuaRocks in GitHub Actions workflow without any hassle 🌛

My Workflow

Submission Category:

Yaml File or Link to Code

MunifTanjim / luver-action

🌛 Set up your GitHub Actions workflow with specific versions of Lua, LuaJIT, LuaRocks using Luver ❤️

Luver GitHub Action

Usage

License

Additional Resources / Info

Performance Optimization - What not to Optimize

Neovim - Build UI using nui.nvim

Enter nui.nvim

UI for LSP Rename using nui.nvim

Basic Middleware Pattern in JavaScript

Implementation

Usage

TypeScript

Built-in Option: `exrc`

Plugin: `exrc.nvim`

Enter `nui.nvim`