Install Plugin

A plugin is still the same thing we mentioned in previous sections, e.g. a single javascript/typescript file is a plugin, a package is a plugin as well.

Difference is the concept: "module" or "package" is how you structure your configurations, while "plugin" is how these configurations are shared and distributed among the community and users.

You need to go to Rsvim config home directory before installing any plugins:

# use $XDG_CONFIG_HOME
cd $XDG_CONFIG_HOME/rsvim

# or use $HOME
cd $HOME/.rsvim

In this section, assume you use $HOME/.rsvim as Rsvim config home, now let's use ex.rsvim as an example to show how to install and use a plugin.

note

The "ex.rsvim" plugin implements Vim's builtin ex commands (such as write, quit) to provide a compatible user experience in command-line. And you don't need to use the annoying js command any more.

Git

First git clone the GitHub repository to your config home:

git clone https://github.com/rsvim/ex.rsvim ex.rsvim

Your config home directory structure will become:

$HOME/.rsvim
|- rsvim.js
|- ex.rsvim/   <-- `ex.rsvim` here
   |- lib/
      |- index.js
      |- ...
   |- src/
      |- index.ts
      |- ...
   |- types/
      |- index.d.ts
      |- ...
   |- README.md
   |- LICENSE.txt
   |- package.json
   |- package-lock.json
   |- ...

ex.rsvim exports a initialization method setup. Let's setup the "ex.rsvim" plugin in your config entry script:

import ex from "ex.rsvim";

ex.setup();

Since Rsvim can recognize the npm package in its config home directory, it will load the plugin entry $HOME/.rsvim/ex.rsvim/lib/index.js, which is specified in its package.json file:

{
  "exports": "./lib/index.js",
  ...
}

Npm

ex.rsvim also publishes as a npm scoped package @rsvim/ex.rsvim, under the official scope @rsvim. Thus we can also install it with npm:

npm install @rsvim/ex.rsvim

Your config home directory will become:

$HOME/.rsvim
|- rsvim.js
|- package.json      <-- create a `package.json` file
|- package-lock.json <-- and a `package-lock.json` file
|- node_modules/
   |- @rsvim/
      |- ex.rsvim/   <-- `ex.rsvim` here
         |- lib/
         |- src/
         |- types/
         |- ...

The newly created package.json file will look like:

{
  "dependencies": {
    "@rsvim/ex.rsvim": "^0.2.0"
  }
}

The setup part is a little different from git clones, your config entry script becomes:

import ex from "@rsvim/ex.rsvim";

ex.setup();

You will have to use npm package name instead of a directory name.

Manage Your Plugins with package.json

With the node_modules looking up, now you can directly use npm to manage all your plugins, even your own Rsvim configurations (your $HOME/.rsvim can also be treated as a package), with a single package.json file.

For example your config home is:

$HOME/.rsvim
|- rsvim.js
|- package.json

package.json

{
  "type": "module",
  "dependencies": {
    "@rsvim/syntax": "^0.1.0",
    "@rsvim/ex": "^0.2.0"
    ...
  }
}

rsvim.js

import syntax from "@rsvim/syntax";
import ex from "@rsvim/ex";

syntax.setup();
ex.setup();

The package.json specifies all the plugins with semantic version support. Run npm install command inside the config home, all plugins will be installed in the node_modules directory.

The config entry rsvim.js can just import these npm packages like node/deno!

warning

Not all plugins in the package.json really exist 😁 (at least for now).

Scoped Package Name Problem

One more thing worth to mention is: A plugin can be installed via both git and npm, and plugins can have their own dependencies. You may encounter the scoped package name problem. For example:

Problem

Suppose both A and B are hosted on GitHub as https://github.com/rsvim/A and https://github.com/rsvim/B, and you install it with git:

git clone https://github.com/rsvim/A A
git clone https://github.com/rsvim/B B

And your config home becomes:

$HOME/.rsvim
|- rsvim.js
|- A/
   |- lib/
      |- index.js
      |- ...
   |- package.json
   |- ...
|- B/
   |- lib/
      |- index.js
      |- ...
   |- package.json
   |- ...

Now, here's our problem, in A/lib/index.js, it tries to call a method from B:

import B from "@rsvim/B";

const value = B.add(1, 2);

In the 1st line, A try to import package B as a npm scoped package, but it can never find B.

Solution

To solve this problem, you must run git clone with its npm scoped package name:

git clone https://github.com/rsvim/A @rsvim/A
git clone https://github.com/rsvim/B @rsvim/B

And your config home looks like:

$HOME/.rsvim
|- rsvim.js
|- @rsvim/
   |- A/
      |- lib/
         |- index.js
         |- ...
      |- package.json
      |- ...
   |- B/
      |- lib/
         |- index.js
         |- ...
      |- package.json
      |- ...

Now A/lib/index.js can find B!