Project Structure

Directory Layout

After running nexusdb init, your project has this structure:

my-project/
├── nexusdb.yaml          # Main configuration
├── .env                  # Environment variables (git-ignored)
├── collections/          # Collection schemas
│   ├── users.json
│   ├── posts.json
│   └── comments.json
├── migrations/           # Schema migrations
│   ├── 001_initial.js
│   └── 002_add_indexes.js
├── seeds/                # Test data
│   └── development.json
├── hooks/                # Lifecycle hooks
│   ├── before-insert.js
│   └── after-update.js
└── plugins/              # Custom plugins
    └── my-plugin.js

Configuration File

The nexusdb.yaml file is the central configuration:

# nexusdb.yaml
server:
  port: 4200
  host: 0.0.0.0

engine:
  type: rocksdb
  data_dir: ./data

auth:
  secret: ${NEXUSDB_SECRET}
  token_expiry: 3600

collections:
  auto_discover: true
  schema_dir: ./collections

migrations:
  dir: ./migrations
  auto_run: false

Collection Schemas

Define each collection in a JSON file under collections/:

{
  "name": "posts",
  "fields": [
    { "name": "title", "type": "string", "required": true },
    { "name": "slug", "type": "string", "unique": true },
    { "name": "content", "type": "string" },
    { "name": "author_id", "type": "string", "ref": "users" },
    { "name": "tags", "type": "array" },
    { "name": "published", "type": "boolean", "default": false },
    { "name": "published_at", "type": "datetime" }
  ],
  "indexes": [
    { "fields": ["slug"], "unique": true },
    { "fields": ["author_id", "published_at"] },
    { "fields": ["tags"], "type": "array" }
  ]
}

Lifecycle Hooks

// hooks/before-insert.js
module.exports = async (document, context) => {
  if (context.collection === "posts" && !document.slug) {
    document.slug = slugify(document.title);
  }
  return document;
};

Development Workflow

1. Define schemas in collections/
2. Run nexusdb dev for hot-reload development
3. Create migrations for schema changes: nexusdb migrate create add_phone_field
4. Seed test data: nexusdb seed --file seeds/development.json
5. Run tests against a clean instance