This is the article I wish I had when I started learning Vim and using it for elixir development. My aim here is to provide a roadmap, a view of the big picture, and a flavor of my workflow without getting into all the nitty gritty. I try to stay out of the weeds by directing you to more detailed sources where possible. This train takes the scenic route through the wild countryside and cities of vim editing. You can use it to travel to all the places, but it's up to you to get off at each station and do you own exploring and detailed learning. Don't worry. The train will still be at the station when you get back!
"Do not let perfection be the enemy of the good." -- Voltaire.
I'm publishing this gist right from the get-go. It has grammar and spellnig mistakes, structural issues, is overly wordly, and has broken or non-existent links. There was a time where I would've waited til this was perfect (whatever that means) before releasing it. But I continually add to it, so please overlook the warts and don't judge me too harshly for them.
Yet.
This article assumes you have no VIM experience and that you are already comfortable developing Elixir/Phoenix in an IDE like VS Code or Atom. But even the experienced VIM developer may find something useful in here. Frankly, writing Elixir in any editor is challenging due to the lack of editing tools taken for granted while working with, say, Angular. A very common painpoint for Phoenix developers, for example, if syntax highlighting and code-formatting of .eex and .leex files. We'll talk abount those here.
I spent the first two years of my software career using VS Code to the exclusion of all else. I'd always been a fan of keyboard shortcuts. In my previous life as a mechanical engineer, I always strove to master keyboard shortcuts, whether it was Chrome, MS Word, or my CAD software. I could never understand why my colleages would reach for a mouse to click on "Header 1" instead of just keying in Alt + Shift (TODO: is that actually correct? I almost never use Word anymore...). When using VS Code, I tried using MetaGo (TODO: is this the right name?) to navigate around my text files without the help of my mouse. But even without that plugin, vanilla VS Code (like all IDEs, I'm sure) has excellent keyboard navigation. File searching, etc. I even wrote my own snippets.
So there I am, happily learning Elixir and Phoenix, struggling like everyone else to properly format their .ex, .eex, and .leex files, when I decide to upgrade Elixir to the newest version. Up until now, I'd been using VS Code in Windows. I'd heard of the asdf tool for managing versions. And I do love consolidating. asdf allowed me to manage versions of python, elixir, erlang, node, etc.
But it's not available on Windows. No big deal, I thought, I'll just install Windows Subsystem for Linux and do all my development there.
Are you familiar with the children's story If You Give a Mouse a Cookie? If you give a mouse a cookie, he'll ask for a glass of milk. And if you give the mouse a glass of milk, he'll... Etc, etc. And so it was for me. Choosing to manage my elixir versions with asdf led me down a rabbit hole that included classic waypoints like choosing to quickly edit a file in VIM and having no idea how to even add text or, worse, how to close the program! A little digging turned into more digging, which led to me purchasing Drew Neil's excellent Practical Vim book from the Pragmatic Bookshelf, and then later his also-excellent Modern Vim.
I am still making my way down through this rabbit hole. But it's time to share what I've learned. This article is the article I wish I'd had when I started on this journey. May it light the way.
There is no substitute for learning the basics of VIM. I highly recommend starting with both the vim tutor and Drew Neil's Practical Vim book. Work throught both of those in whatever order you please. The tutor will give you actual pracice and start to develop you muscle memory. The book provides a lot of techniques, but more importantly, it shows you the vim way of thinking.
Add a new plugin:
- Add a line such as
call minpac#add('tpope/vim-surround')to.vimrc. Save and reload vim. - run
:PackUpdate. This downloads and installs the plugin.
Update plugins:
- run
:PackUpdateagain.
Remove a plugin:
- Remove the
call minpac#add...line from.vimrc. Save and reload. - run
:PackClean
This is all possible via Vim 8's built-in package management and the ultra-simple minpac package manager. You'll see recommendations all over the web and in vim package readme's that recommend using package managers like pathogen and vim-plug (I used this one for a while). But I really don't think you need those. Isn't the above workflow simple enough? I don't need any more bells and whistles right now. I'll update this if I change my mind though.
TODO: talk about my arkrc; adding new types for (l)eex
I love Elixir, Phoenix, and LiveView. But damn is it annoying working with .eex and .leex files. Code formatters get confused. Syntax highlighting is dodgy. Lots of google searching and experimentation has led me to the following solution. This is the best I've come up with. PLEASE, if you have a better way of doing this, let me know.
This part if handled mostly via the vim-polyglot plugin.
I'm still experimenting here (2021 Jan 09). It's not mature enough to share the specifics, but basically here's how it works:
- Add the Prettier formatter to your project. Make sure you can format a file from the command line.
- Write a bash or vim script that will replace all your elixir tags (
<%= ... %>) with a string of X's of same lenghth. Save these tags off in a separate temp file or buffer. - Format with Prettier. Save file.
- Replace X-strings with origin elixir tags. Save.
- Delete temp file/buffer.
This script can easily be run with a command like <Leader>p.
- Starting to experiment with emmet-vim. I'll report back on what I find.
- vim-surround is very handy for e.g. changing
"such and such"to'such and such'. Or changing<p>Such and such</p>to plainSuch and suchby deleting the tags in one fell swoop. - Vanilla VIM has some excellent tools already. It lets me work with text objects (that's not the right term for it though...) so if for example I have my cursor somewhere on the text within the double quotes here:
class="text-red-500 font-bold text-xl", I can keyci"to delete all the quoted text and drop into Insert mode with my cursor ready to insert text between the quotes:class="". Again, try to master the vanilla tool and add onto it afterwards. - I add 'leader' commands to my vimrc to make it faster to add e.g. inline if statements. See the vimrc for details.
I strongly recommend not copying my vim file 1:1. Have you own file and slowly add to it. As you add to it, make sure you know what each piece does. Know the vanilla vim tool before making radical changes. Did I follow that advice? No. But I also didn't read this article before making that choice. There is too much going on in a custom vim setup to make sense of it at one time. Master basic vim first working on a side project, and slowly pepper all this other stuff in.
https://github.com/jonathanchukinas/dotfiles/blob/main/dotfile/.vim/vimrc
I run a Linux distro from System 76 called Pop!_OS. They have a pretty nice tile manager and I make good use of that. Within vim I use vanilla command to manage multiple windows:
<C-h/j/k/l>moves the current window to the far left/bottom/top/right. This is the only custom command I use<C-w>h/j/k/l>selects the window in that direction:vs <filename>opens a file in vertical split screen.Vtemplate cardopens the.eextemplate for my card component. Yet another use of the awesomeprojectionistplugin mentioned above.