@vimazing/vim-sudoku

Lightweight, typed React hooks and utilities for building interactive sudoku games with VIM-inspired controls.

Part of the VIMazing project.

Features
Installation
Quick Start
Core Hooks
Utilities
Example App
Build & Release
License

Features

Drop-in hooks for sudoku game logic, player control, scoring, and key logging.
Typed API with generated declaration files for editor IntelliSense.
VIM-style navigation (h, j, k, l, counts, i to start, etc.).
Composable architecture – bring your own rendering and platform-specific bindings.
Tree-shakeable exports to keep bundles lean.

Installation

Using npm:

npm install @vimazing/vim-sudoku

Or with bun:

bun add @vimazing/vim-sudoku

Quick Start

import { useEffect } from "react";
import { useGame } from "@vimazing/vim-sudoku";

export function SudokuGame() {
  const { containerRef, gameStatus, startGame } = useGame();

  useEffect(() => {
    startGame();
  }, [startGame]);

  return (
    <section className="mx-auto w-fit space-y-4">
      <h1 className="text-2xl font-bold">VIMazing Sudoku</h1>
      <div ref={containerRef} className="relative" />
      {gameStatus === "game-won" && <p>🎉 You solved it!</p>}
    </section>
  );
}

Default controls:

Key	Action
`i`	Start game
`h` / `j` / `k` / `l`	Move cursor
`<number>`	Enter number
`x` / `d`	Clear cell
`q`	Quit game
`Esc`	Cancel / pause

Core Hooks

Hook	Description
`useGame(platformHook?)`	One-stop hook that wires sudoku generation, rendering, player state, scoring, and keyboard bindings. Returns refs, status helpers, and managers you can compose with your UI.
`useKeyBindings()`	Provides VIM-style key bindings, including repeat counts and movement helpers.
`useScore()`	Tracks timers, moves, and final score calculation.

Each hook is exported individually, so you can cherry-pick only what you need:

import { useScore } from "@vimazing/vim-sudoku/useScore";

Utilities

Besides the hooks, the library exports:

SudokuGenerator – procedural sudoku puzzle generation class.
SudokuRenderer – canvas renderer tailored for sudoku grids.
types – shared TypeScript types such as GameStatus, SudokuCell, and KeyLogEntry.

import { SudokuGenerator, GameStatus } from "@vimazing/vim-sudoku";

Example App

A demo application lives under example/ and consumes the package directly.

cd example
bun install
bun run dev

During local development the Vite config aliases @vimazing/vim-sudoku to the source folder so you can iterate without rebuilding. When publishing, run the build first (see below) so editors consume the generated declarations in dist/.

Build & Release

Build the distributable bundle and type declarations:

bun run build

This writes JavaScript, type definitions, and styles to dist/. The prepublishOnly hook reuses the same command to guarantee fresh artifacts before publishing.

3.5 KiB Raw Blame History Unescape Escape