Getting Started

Follow this guide to set up Lazy Appwrite in your Node.js or Serverless project.

Installation

Lazy Appwrite sits on top of the official SDK. You need to install both.

npm install lazy-appwrite node-appwrite 

pnpm add lazy-appwrite node-appwrite 

yarn add lazy-appwrite node-appwrite 

bun add lazy-appwrite node-appwrite 

Quick Start (Recommended)

The fastest way to scaffold your project is using the CLI.

npx lazy-appwrite init

This interactive command will:

1. Ask where to create your configuration file (default: src/lib/appwrite.ts).
2. Generate a production-ready Client setup.
3. Create a lazy-examples/ folder with sample schemas and usage guides.

After running init: Add your credentials to your .env file:

APPWRITE_ENDPOINT=[https://cloud.appwrite.io/v1](https://cloud.appwrite.io/v1)
APPWRITE_PROJECT_ID=your_project_id
APPWRITE_API_KEY=your_secret_api_key

Manual Setup

If you prefer to configure everything from scratch, follow these steps.

import { LazyAppwrite } from "lazy-appwrite";
 
// 1. Create the App Instance
const app = LazyAppwrite.createAdminClient({
  endpoint:
    process.env.APPWRITE_ENDPOINT ||
    "[https://cloud.appwrite.io/v1](https://cloud.appwrite.io/v1)",
  projectId: process.env.APPWRITE_PROJECT_ID!,
  apiKey: process.env.APPWRITE_API_KEY!,
  verbose: process.env.NODE_ENV === "development", // Logs "Creating Table..." only in dev
});
 
// 2. Select your Database
// If "my-main-db" doesn't exist, it will be created automatically.
const db = app.getDatabase("my-main-db", "Main Database");
 
export { db };

import { TableSchema, ColumnType, IndexType } from "lazy-appwrite";
 
export const UserSchema: TableSchema = {
  id: "users",
  name: "Users",
  columns: [
    { key: "username", type: ColumnType.String, size: 50, required: true },
    { key: "age", type: ColumnType.Integer, required: false, _default: 18 },
    {
      key: "is_active",
      type: ColumnType.Boolean,
      required: true,
      _default: true,
    },
  ],
  indexes: [
    { key: "idx_username", type: IndexType.Unique, columns: ["username"] },
  ],
};

import { db } from "./appwrite";
import { UserSchema } from "./schemas";
 
export const Users = db.model(UserSchema);

Existing Projects (Reverse Engineering)

If you already have a database created in the Appwrite Console, you don’t need to write schemas manually. You can Pull your existing structure into TypeScript.

1. Prerequisites

Ensure you have a .env file in your project root with your Admin credentials:

APPWRITE_ENDPOINT=[https://cloud.appwrite.io/v1](https://cloud.appwrite.io/v1)
APPWRITE_PROJECT_ID=...
APPWRITE_API_KEY=...

2. Run the Pull Command

npx lazy-appwrite pull

3. Follow the Prompts

The CLI will read your environment variables and ask you:

1. Which Database to pull (if you have multiple).
2. Where to save the schema file (default: src/lib/schemas.ts).

Note: Make sure to create Models after schema generated.

Usage

Now you can use the Users model in your application logic. The first time you run a command, Lazy Appwrite will ensure the database infrastructure exists.

Creating Data

import { Users } from "@/lib/models";
 
async function signup() {
  // Triggers Lazy Creation if table is missing
  const user = await Users.create({
    username: "LazyDev",
    age: 25,
    // is_active defaults to true
  });
 
  console.log(`Created User ID: ${user.$id}`);
}

Reading Data

We support a simplified query syntax for common operations.

// Find all active users (AND logic)
const activeUsers = await Users.list({
  is_active: true,
});
 
// Advanced queries using the raw SDK Query class
import { Query } from "lazy-appwrite"; // Re-exported for convenience
 
const adults = await Users.list([Query.greaterThan("age", 18)]);