Skip to main content

​
Install Esix

Esix requires Node.js 20 or higher and works with MongoDB 4.0+. 
npm install esix mongodb
Esix has mongodb as a peer dependency. You must install both esix and mongodb packages.

​
Configure MongoDB connection

Esix automatically connects to MongoDB when needed. Configure your connection using environment variables:

​
Set connection string

The simplest way to configure Esix is with the DB_URL environment variable: 
export DB_URL=mongodb://localhost:27017/myapp
For production deployments with MongoDB Atlas or other cloud providers: 
export DB_URL=mongodb+srv://username:password@cluster.mongodb.net/myapp

​
Environment variables reference

Esix supports the following environment variables:
​
DB_URL
string
required
MongoDB connection string. This is the primary configuration option and the only required variable.
DB_URL=mongodb://localhost:27017/myapp
​
DB_DATABASE
string
Database name. Optional—Esix extracts the database name from DB_URL if not provided.
DB_DATABASE=myapp
​
DB_ADAPTER
string
Database adapter. Set to 'mock' for testing with in-memory MongoDB. Defaults to the standard MongoDB driver.
DB_ADAPTER=mock

​
Verify installation

Create a simple test file to verify your installation:
test.ts
import { BaseModel } from 'esix'

class User extends BaseModel {
  public name = ''
  public email = ''
}

async function test() {
  // Create a user
  const user = await User.create({
    name: 'Test User',
    email: 'test@example.com'
  })

  console.log('Created user:', user.id)

  // Find the user
  const found = await User.find(user.id)
  console.log('Found user:', found?.name)

  // Count users
  const count = await User.count()
  console.log('Total users:', count)
}

test().catch(console.error)
Run the test: 
npx tsx test.ts
If everything is configured correctly, you should see output showing the created user’s ID, name, and total count.

​
TypeScript configuration

Esix requires the following TypeScript compiler options in your tsconfig.json:
tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "moduleResolution": "node",
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "strict": true
  }
}
The experimentalDecorators and emitDecoratorMetadata options are required for Esix’s internal metadata handling, even though you won’t use decorators in your model definitions.

​
Testing setup

For testing, you can use an in-memory MongoDB mock or a test database: Install the mock adapter: 
npm install --save-dev mongo-mock
Configure your test environment: 
DB_ADAPTER=mock
DB_URL=mongodb://localhost:27017/test

​
Option 2: Dedicated test database

Use a separate database for testing: 
DB_URL=mongodb://localhost:27017/myapp_test
For integration tests, consider using a tool like mongodb-memory-server to spin up temporary MongoDB instances.

​
Docker setup

If you need a local MongoDB instance for development, use Docker: 
docker run -d \
  --name mongodb \
  -p 27017:27017 \
  -e MONGO_INITDB_DATABASE=myapp \
  mongo:latest
Then set your connection string: 
export DB_URL=mongodb://localhost:27017/myapp

​
Connection management

Esix automatically manages your MongoDB connection:
  • Lazy connection: The connection is established when you first query the database, not when your application starts
  • Connection pooling: MongoDB’s native connection pooling is used automatically
  • No manual cleanup: You don’t need to explicitly close connections
The automatic connection management means you can start writing queries immediately without any initialization code.

​
Next steps

Quickstart

Build your first Esix application with a complete working example