# croxydb

> a JSON/YAML/LocalStorage/MongoDB/MySQL/Firebase database module with a built-in web panel

Latest version **0.0.27** (published 2026-07-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install croxydb
pnpm add croxydb
yarn add croxydb
bun add croxydb
```

## Health

**Score 50/100 (C)** — status: active.

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.0.27 |
| Published | 2026-07-25 |
| First published | 2020-07-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 120 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 8 |
| Author | croxydeveloper |
| Maintainers | croxy |
| Keywords | croxy, croxy-api, croxyapi, croxydb, croxy-db, json, jsondb, yaml, yamldb, local, localstorage, local storage, node-json-db, db, mongo, mysql, firebase, mongoose, mongodb, database |

## Links

- npm: https://www.npmjs.com/package/croxydb
- Repository: https://github.com/croxydev/croxydb
- Homepage: https://github.com/croxydeveloper/croxydb#readme
- Issues: https://github.com/croxydeveloper/croxydb/issues
- npm.io page: https://npm.io/package/croxydb

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 0.0.27 (latest) — 2026-07-25
- 0.0.26 — 2024-09-25
- 0.0.25 — 2024-07-31
- 0.0.24 — 2024-04-27
- 0.0.23 — 2024-04-19
- 0.0.22 — 2023-09-12
- 0.0.21 — 2023-09-12
- 0.0.20 — 2023-09-12
- 0.0.19 — 2023-09-12
- 0.0.18 — 2023-09-12
- 0.0.17 — 2023-09-12
- 0.0.16 — 2023-09-12
- 0.0.15 — 2023-09-12
- 0.0.14 — 2023-09-12
- 0.0.13 — 2023-09-12
- … 11 more at https://npm.io/package/croxydb/versions

## README

# CroxyDB

![Downloads](https://img.shields.io/npm/dt/croxydb.svg?style=flat-square) ![Monthly Downloads](https://img.shields.io/npm/dm/croxydb.svg?style=flat-square) ![Weekly Downloads](https://img.shields.io/npm/dw/croxydb.svg?style=flat-square) ![License](https://img.shields.io/npm/l/croxydb.svg?style=flat-square)

Discord: https://discord.gg/uemHZfU6ve

## English

CroxyDB is a small key-value database module for Node.js. It supports JSON, YAML, LocalStorage, MongoDB, MySQL, and Firebase adapters. The default adapter is JSON.

### Version 0.0.27 changes

- Added real independent instances with `db.createInstance()`.
- Added scoped paths with `db.path("users")`.
- Fixed storing `0`, `false`, and `""`.
- Added deep-cloned return values to avoid caller reference mutation bugs.
- Added sync and async APIs together.
- Added TTL support with `db.set(key, value, { ttl })`.
- Added events: `set`, `delete`, `expire`, and `deleteAll`.
- Added crash-safe JSON writes with temp file plus rename.
- Added optional AES-256-GCM encryption for JSON storage.
- Added a small migration runner.
- Update checks are enabled by default and run during operations.
- Update check warnings include the Discord invite.
- Updated the Discord invite link.
- Added MySQL adapter.
- Added Firebase adapter.
- Added optional peer dependencies for `mysql2` and `firebase-admin`.
- Added a dependency-free web panel.
- Added web panel options for auth, readonly mode, theme, import/export, and delete-all control.
- Updated TypeScript definitions for new adapters, web panel options, async methods, instances, TTL, and events.
- Reworked this README into a simpler English and Turkish document.
- Bumped package version to `0.0.27`.

### Install

```bash
npm install croxydb
```

Optional adapter packages:

```bash
npm install mysql2
npm install firebase-admin
npm install mongoose
npm install yaml
```

### Basic usage

```js
const db = require("croxydb")

db.set("user.name", "Ada")
db.get("user") // { name: "Ada" }

db.set("zero", 0)
db.set("enabled", false)
db.set("empty", "")

db.has("enabled") // true
db.delete("user.name") // true
db.all()
```

### Arrays and numbers

```js
db.add("coins", 10)
db.subtract("coins", 3)

db.push("items", "sword")
db.push("items", "shield")
db.unpush("items", "sword")
```

### Instances

```js
const usersDb = db.createInstance({
  folder: "data",
  file: "users"
})

usersDb.set("1.name", "Ada")
```

### Scoped paths

```js
const users = db.path("users")

users.set("1", { name: "Ada" })
users.get("1")
```

### Async API

```js
await db.setAsync("settings.theme", "dark")
await db.getAsync("settings.theme")
```

### TTL

```js
db.set("session.token", "abc", { ttl: 60_000 })
```

### Events

```js
db.on("set", (key, value) => {
  console.log(key, value)
})

db.on("expire", (key) => {
  console.log("expired", key)
})
```

### Encryption

```js
db.setEncryptionKey("your-secret")
db.set("private.value", "encrypted at rest")
```

### Web panel

The web panel uses only Node.js built-in modules.

```js
db.setWebPanel(true, 2229, {
  title: "CroxyDB Admin",
  password: "secret",
  readonly: false,
  theme: {
    primary: "#30d158",
    background: "#050506",
    surface: "#151516",
    muted: "#8e8e93",
    text: "#f5f5f7"
  },
  actions: {
    import: true,
    export: true,
    deleteAll: false
  }
})
```

Open:

```text
http://localhost:2229
```

### MySQL adapter

Install `mysql2` first.

```js
db.setAdapter("mysql", {
  host: "localhost",
  user: "root",
  password: "password",
  database: "my_database",
  table: "croxydb"
})

await db.setAsync("users.1", { name: "Ada" })
await db.getAsync("users.1")
```

Connection URL is also supported:

```js
db.setAdapter("mysql", {
  url: "mysql://root:password@localhost:3306/my_database",
  table: "croxydb"
})
```

### Firebase adapter

Install `firebase-admin` first.

```js
db.setAdapter("firebase", {
  databaseURL: "https://your-project-default-rtdb.firebaseio.com",
  serviceAccount: require("./service-account.json"),
  path: "croxydb"
})

await db.setAsync("users.1", { name: "Ada" })
await db.getAsync("users.1")
```

### MongoDB adapter

Install `mongoose` first.

```js
db.setAdapter("mongo", {
  url: "mongodb://localhost/database",
  schema: "CroxyDB"
})

await db.set("users.1", { name: "Ada" })
await db.get("users.1")
```

### Options

```js
db.setReadable(true)
db.setNoBlankData(true)
db.setFolder("database")
db.setFile("main")
db.setSeperator(".")
db.setCheckUpdates(false) // disable update checks
```

### Migration

```js
db.registerMigration("rename-key", async (database) => {
  const oldValue = await database.getAsync("old.key")
  if (oldValue !== undefined) {
    await database.setAsync("new.key", oldValue)
    await database.deleteAsync("old.key")
  }
})

await db.migrate()
```

## Turkish

CroxyDB, Node.js icin kucuk bir key-value database moduludur. JSON, YAML, LocalStorage, MongoDB, MySQL ve Firebase adapterlerini destekler. Varsayilan adapter JSON adapteridir.


### 0.0.27 degisiklikleri

- `db.createInstance()` ile gercek bagimsiz instance destegi eklendi.
- `db.path("users")` ile scoped path sistemi eklendi.
- `0`, `false` ve `""` kaydetme sorunu duzeltildi.
- Disaridan referans mutasyonu olmasin diye donen objeler deep clone yapiliyor.
- Sync ve async API birlikte eklendi.
- `db.set(key, value, { ttl })` ile TTL destegi eklendi.
- `set`, `delete`, `expire`, `deleteAll` eventleri eklendi.
- JSON adapter icin temp dosya ve rename ile crash-safe yazma eklendi.
- JSON storage icin opsiyonel AES-256-GCM sifreleme eklendi.
- Basit migration runner eklendi.
- Update check varsayilan olarak acik gelir ve islemler sirasinda calisir.
- Update check uyarilarinda Discord davet linki bulunur.
- Discord davet linki guncellendi.
- MySQL adapter eklendi.
- Firebase adapter eklendi.
- `mysql2` ve `firebase-admin` optional peer dependency olarak eklendi.
- Dependency kullanmayan web panel eklendi.
- Web panel icin auth, readonly mode, tema, import/export ve delete-all kontrolu eklendi.
- TypeScript tanimlari yeni adapterler, web panel, async metotlar, instance, TTL ve eventler icin guncellendi.
- README daha sade Ingilizce ve Turkce dokuman olarak yenilendi.
- Paket surumu `0.0.27` yapildi.

### Kurulum

```bash
npm install croxydb
```

Opsiyonel adapter paketleri:

```bash
npm install mysql2
npm install firebase-admin
npm install mongoose
npm install yaml
```

### Temel kullanim

```js
const db = require("croxydb")

db.set("user.name", "Ada")
db.get("user") // { name: "Ada" }

db.set("zero", 0)
db.set("enabled", false)
db.set("empty", "")

db.has("enabled") // true
db.delete("user.name") // true
db.all()
```

### Web panel

```js
db.setWebPanel(true, 2229, {
  title: "CroxyDB Admin",
  password: "secret",
  readonly: false,
  actions: {
    import: true,
    export: true,
    deleteAll: false
  }
})
```

Adres:

```text
http://localhost:2229
```

### MySQL

```js
db.setAdapter("mysql", {
  host: "localhost",
  user: "root",
  password: "password",
  database: "my_database",
  table: "croxydb"
})

await db.setAsync("users.1", { name: "Ada" })
```

### Firebase

```js
db.setAdapter("firebase", {
  databaseURL: "https://your-project-default-rtdb.firebaseio.com",
  serviceAccount: require("./service-account.json"),
  path: "croxydb"
})

await db.setAsync("users.1", { name: "Ada" })
```

### Destek

Discord: https://discord.gg/uemHZfU6ve

---
_Source: https://npm.io/package/croxydb · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._