Directus Telescope Extension

telescope-directus.nvim

• Managing Headless CMS Content from Neovim

As a backend developer, I spend the majority of my time in Neovim. Switching to a browser just to update a schema or check a content entry in my CMS feels like a break in flow. To solve this, I built a custom Telescope extension that allows me to perform CRUD operations on a Directus instance without leaving the terminal.

Setup

Telescope plugin set up example using lazy.nvim as the package manager Requires a url and token with proper credentials show_hidden field is optional to control the fields which are shown

return {
    "Brady-MacDonald/telescope-directus.nvim",
    dependencies = { 'nvim-telescope/telescope.nvim' },
    config = function()
        local directus = require("directus")

        directus.setup({
            url = "http://localhost:8055",
            token = "1234",
            show_hidden = true
        })

        vim.keymap.set("n", "<leader>dc", directus.directus_collections, { desc = "Directus Collection" })
    end
}

🛠 The Problem

Directus is a powerful headless CMS, but interacting with its API usually requires using their (admittedly great) web UI or writing manual curl scripts. I wanted a way to: Quickly browse collections. View specific item details. Perform basic edits or deletes directly from my editor.

🚀 Features

Collection Browsing: Use Telescope's fuzzy finding to navigate through your Directus collections. Live Preview: View item JSON or specific fields in a Telescope previewer. CRUD Actions: Create: Initialize new items using a temporary buffer. Read: Fetch real-time data from the Directus REST API. Update/Delete: Modify or remove entries using mapped keybindings.

🏗 Technical Implementation

The Backend: Directus API

The extension communicates with the Directus REST API. I utilized Lua's plenary.curl to handle asynchronous requests, ensuring that the Neovim UI doesn't freeze while waiting for a response from the CMS. The Frontend: Telescope Pickers

The core of the plugin is built on the Telescope.nvim API. I implemented:

• Finders: To query the Directus /items/ endpoints.
• Sorters: To allow for quick filtering of large datasets.
• Previewers: To syntax-highlight the JSON data returned by the API for better readability.

local pickers = require("telescope.pickers")
local finders = require("telescope.finders")

User commands offer tab completion

    :Directus collections
    :Directus fields <collection>

🧠 Challenges Overcome

Authentication & Security

Managing API tokens securely within a Neovim config was a priority. I designed the plugin to read environment variables or an encrypted local file, ensuring that sensitive Directus credentials are never hardcoded. Handling Dynamic Schemas

Directus collections are dynamic. I had to ensure the Telescope previewer could handle varying JSON structures gracefully, regardless of how complex the data model is.

🔧 Future Roadmap

Schema Inspection: Browsing the data model itself, not just the items. Media Management: Using a tool like chafa to preview Directus assets directly in the terminal. Bi-directional Sync: Better handling of conflicts when multiple users are editing the same collection.