swizzy-nvim

Neovim plugin for scaffolding and managing @swizzyweb/swizzy-web-service projects. Feature-parity with swizzy-web-service-cli via Neovim commands.

Installation

LazyVim

Create a new file ~/.config/nvim/lua/plugins/swizzy.lua:

return {
  dir = "/path/to/swizzy-nvim",
  name = "swizzy-nvim",
  config = function()
    require("swizzy").setup({})
  end,
}

Replace /path/to/swizzy-nvim with the absolute path to this repository. Then reload with :Lazy reload swizzy-nvim or restart Neovim.

lazy.nvim (standalone)

{
  "swizzyweb/swizzy-nvim",
  config = function()
    require("swizzy").setup({})
  end,
}

Default options

require("swizzy").setup({
  cd_on_create   = true,   -- :cd into newly created web service directories
  open_on_create = true,   -- open generated files in the editor
})

---

Commands

:SwizzyCreateWebService

Scaffold a new swizzy-web-service project by cloning the official template.

Prompts for:

1. Service name — PascalCase (e.g. MyApi)
2. Service type — Backend (API only) or Frontend (React + API)
3. npm scope — optional (e.g. myorg → @myorg/my-api-web-service)
4. Run npm install — Yes / No

Creates a new project directory at ./<kebab-name>-web-service/ relative to the current working directory, removes .git, and updates package.json.

---

:SwizzyCreateRouter

Add a new WebRouter to the project in the current directory.

Prompts for:

1. Router name — PascalCase (e.g. Message)
2. URL path segment — (e.g. message)
3. Include standard middleware — SwizzyRequestMiddleware, RequestIdMiddleware, RequestLoggerMiddleware

Creates: src/routers/MessageRouter/message-router.ts Patches: src/web-service.ts — adds import and appends to routerClasses Opens: the new router file

---

:SwizzyCreateController

Add a new WebController to an existing router.

Prompts for:

1. Controller name — PascalCase (e.g. SendMessage)
2. Action / URL segment — (e.g. send)
3. HTTP method — GET / POST / PUT / DELETE / PATCH
4. Parent router — selected from detected routers in the project
5. Request input type — None / Request body (JSON) / Query params
6. State fields — optional comma-separated name: Type pairs (e.g. authService: IAuthService)
7. Service arguments — optional comma-separated name: type pairs (e.g. authBaseUrl: string)

Creates:

• src/routers/MessageRouter/controllers/send-controller.ts
• test/routers/MessageRouter/controllers/send-controller.spec.ts

Patches: src/routers/MessageRouter/message-router.ts — adds import and appends to webControllerClasses Opens: the new controller file

---

:SwizzyCreateMiddleware

Add a standalone SwizzyMiddleware to an existing router or controller.

Prompts for:

1. Middleware name — PascalCase without the Middleware suffix (e.g. Auth → AuthMiddleware)
2. Scope — Router or Controller
3. Parent router — selected from detected routers
4. Parent controller — (controller scope only) selected from controllers in the chosen router

Creates: src/routers/MessageRouter/middleware/auth-middleware.ts

Patches (router scope): src/routers/MessageRouter/message-router.ts — adds import and appends AuthMiddleware to middleware

Patches (controller scope): src/routers/MessageRouter/controllers/send-controller.ts — adds import and appends AuthMiddleware to middleware

Opens: the new middleware file

---

:SwizzyBuild

Build the project in the current directory.

Runs npm run build in a horizontal split terminal.

---

:SwizzyRun [port]

Open a terminal split and start the swerve server.

:SwizzyRun
:SwizzyRun 3005

Runs node_modules/.bin/swerve [--port PORT] in a horizontal split terminal. Press Ctrl+C inside the terminal to stop.

---

:SwizzyDev [port]

Open two terminal splits: tsc --watch + swerve.

:SwizzyDev
:SwizzyDev 3005

Opens a horizontal split with tsc --watch and a vertical split with swerve. Recompilation and server restart are handled by the running processes.

---

:SwizzyDeleteController

Delete a WebController and its test file, and remove it from the parent router.

Prompts for the router, then the controller to delete, then asks for confirmation.

---

:SwizzyDeleteRouter

Delete a WebRouter directory and remove it from src/web-service.ts.

Prompts for the router to delete, then asks for confirmation.

---

:SwizzyDeleteMiddleware

Delete a SwizzyMiddleware file and remove it from its parent router or controller.

---

:SwizzyRenameController

Rename a WebController — updates the class name, file name, and all import references.

---

:SwizzyRenameRouter

Rename a WebRouter — updates the class name, directory, file name, and all import references.

---

:SwizzyRenameMiddleware

Rename a SwizzyMiddleware — updates the class name, file name, and all import references.

---

:SwizzyGenerateTests

Generate multi-case test stubs for all routers and controllers in the current project. Produces a shared test helper and individual test files with happy-path (200), per-missing-field (400), and error (500) cases using @swizzyweb/swizzy-web-service-test-framework.

Existing test files are skipped. Runs in a terminal split so output is visible.

---

:SwizzyGenerateSpec

Generate an OpenAPI 3.0 spec from the current swizzy-web-service project by introspecting routers and controllers.

Prompts for:

1. Output file — leave empty for openapi.yaml in the project root
2. Server URL — optional (e.g. http://localhost:3000)
3. API version — leave empty for 1.0.0
4. Output format — YAML or JSON

Runs in a terminal split so output is visible.

---

:SwizzyGenerateSkeleton

Generate a swizzy-web-service project skeleton from an OpenAPI 3.0 spec. Creates routers, controllers, models, and services wired together from the paths defined in the spec.

Prompts for:

1. Spec file path — required, path to a .json or .yaml OpenAPI 3.0 file
2. Output directory — leave empty for ./generated
3. Service name — optional PascalCase override
4. npm scope — optional (e.g. myorg)
5. API base path — leave empty for api

Runs in a terminal split so output is visible.

---

:SwizzyCLI [args...]

Run the swizzy CLI directly in a terminal split, passing any arguments through.

:SwizzyCLI generate-spec --json
:SwizzyCLI create-router --name Health --path health

Uses the project-local binary at node_modules/.bin/swizzy if present, otherwise falls back to the globally installed swizzy.

---

Naming Conventions

Given a service name of MyApi:

Derived	Value
Project directory	my-api-web-service/
Package name	@scope/my-api-web-service
Service class	MyApiWebService

Given a router name of Message:

Derived	Value
Class name	MessageWebRouter
File name	message-router.ts
Directory	src/routers/MessageRouter/
State type	MessageRouterState

Given a controller name of SendMessage with action send:

Derived	Value
Class name	SendMessageController
File name	send-controller.ts
Directory	src/routers/MessageRouter/controllers/
State type	SendMessageControllerState

Given a middleware name of Auth:

Derived	Value
Exported name	AuthMiddleware
File name	auth-middleware.ts
Directory	src/routers/MessageRouter/middleware/

---

Requirements

• Neovim 0.9+
• git available in $PATH (for :SwizzyCreateWebService)
• A swizzy-web-service project with @swizzyweb/swizzy-web-service in dependencies (for router/controller/generate commands)
• @swizzyweb/swizzy-web-service-cli installed locally or globally (for :SwizzyGenerateTests, :SwizzyGenerateSpec, :SwizzyGenerateSkeleton, :SwizzyCLI)