Vimcraft Docs / Editor API

Editor API Reference

Vimcraft provides a Neovim-compatible API for configuration and plugins, powered by TypeScript with full IntelliSense support.

API Modules

Core APIs

ModuleDescription
vim.apiLow-level buffer, window, autocommand, and user command functions
vim.optEditor options (number, cursorLine, tabStop, etc.)
vim.keymapKey mapping system for custom keybindings
vim.highlightSyntax highlighting and theme customization
vim.g/b/w/t/vVariable scopes (global, buffer, window, tab, vim)

Motion & Cursor

ModuleDescription
vim.motionProgrammatic cursor movement (left, right, wordForward, etc.)
vim.cursorCursor position and render override for animations
vim.bufferZero-copy buffer content access

Editor Features

ModuleDescription
vim.cmdExecute Ex commands
vim.filetypeFile type detection (~1,200 types)
vim.fnVimscript function bridge

Testing

ModuleDescription
vim.e2eEnd-to-end testing framework

Quick Start

// ~/.config/vimcraft/index.ts

// Leader key
vim.g.mapLeader = ' ';

// Display options
vim.opt.number = true;
vim.opt.relativeNumber = true;
vim.opt.cursorLine = true;
vim.opt.scrollOff = 8;

// Keymaps
vim.keymap.set('n', '<leader>w', ':w<CR>', { desc: 'Save file' });
vim.keymap.set('n', '<leader>q', ':q<CR>', { desc: 'Quit' });

// Autocommands
vim.api.createAutocmd('FileType', {
  pattern: 'typescript',
  callback: () => {
    vim.opt.tabStop = 2;
    vim.opt.shiftWidth = 2;
  }
});

// Custom command
vim.api.createUserCmd('Hello', () => {
  console.log('Hello from Vimcraft!');
}, { desc: 'Say hello' });

console.log('Vimcraft configured!');

vim.opt - Editor Options

Configure the editor with ergonomic property syntax.

// Display
vim.opt.number = true;
vim.opt.relativeNumber = true;
vim.opt.cursorLine = true;
vim.opt.signColumn = 'yes';

// Indentation
vim.opt.tabStop = 2;
vim.opt.shiftWidth = 2;
vim.opt.expandTab = true;

// Search
vim.opt.ignoreCase = true;
vim.opt.smartCase = true;
vim.opt.hlSearch = true;

// Behavior
vim.opt.scrollOff = 8;
vim.opt.splitRight = true;
vim.opt.splitBelow = true;

See vim.opt for 70+ available options.

vim.keymap - Key Bindings

Create custom keybindings with callback support.

// Command string
vim.keymap.set('n', '<leader>ff', ':find<CR>');

// Callback function
vim.keymap.set('n', '<leader>bd', () => {
  const buf = vim.api.getCurrentBuf();
  vim.api.bufDelete(buf, { force: false });
});

// Multiple modes
vim.keymap.set(['n', 'v'], '<leader>y', '"+y');

See vim.keymap for full documentation.

vim.highlight - Theming

Customize syntax highlighting and editor colors.

// Syntax highlighting
vim.highlight('Comment', { fg: '#6c6c6c', italic: true });
vim.highlight('Function', { fg: '#61afef', bold: true });
vim.highlight('String', { fg: '#98c379' });

// Editor elements
vim.highlight('CursorLine', { bg: '#2c323c' });
vim.highlight('LineNr', { fg: '#5a5a5a' });
vim.highlight('Visual', { bg: '#264f78' });

See vim.highlight for all options.

vim.api - Low-Level API

Direct editor manipulation with Neovim-compatible functions.

// Buffer operations
const buf = vim.api.getCurrentBuf();
const lines = vim.api.bufGetLines(buf, 0, -1, false);
vim.api.bufSetLines(buf, 0, 1, false, ['New first line']);

// Window operations
const win = vim.api.getCurrentWin();
const [row, col] = vim.api.winGetCursor(win);
vim.api.winSetCursor(win, [10, 0]);

// Autocommands
vim.api.createAutocmd('BufWritePre', {
  pattern: '*.ts',
  callback: () => console.log('Saving TypeScript file...')
});

// User commands
vim.api.createUserCmd('Format', () => {
  console.log('Formatting...');
}, { desc: 'Format buffer' });

See vim.api for all functions.

Variables and Scopes

// Global (vim.g)
vim.g.mapLeader = ' ';
vim.g.myPlugin = { enabled: true };

// Buffer-local (vim.b)
vim.b.customFormatter = 'prettier';

// Window-local (vim.w)
vim.w.statusLineActive = true;

// Tab-local (vim.t)
vim.t.tabName = 'Development';

// Vim variables - read-only (vim.v)
const count = vim.v.count;

See Variables & Scopes for details.