Installation

Install and configure @igniter-js/collections for your runtime. Choose the right adapter and set up your first collection in minutes.

Installation

@igniter-js/collections works on Node.js 18+ and Bun 1.0+. It requires zod (or any StandardSchemaV1-compatible validator) as a peer dependency.

npm install @igniter-js/collections zod
pnpm add @igniter-js/collections zod
yarn add @igniter-js/collections zod
bun add @igniter-js/collections zod

Zod is the recommended schema library. Collections uses the StandardSchemaV1 interface, so any compatible validator (Valibot, ArkType) works, but Zod has first-class testing and the best inference story.

Choosing an Adapter

The adapter determines where your files are stored. Collections ships with five adapters, each optimized for a specific use case:

AdapterImport PathBest For
NodeFsAdapter@igniter-js/collections/adaptersNode.js server-side apps, local development
BunFsAdapter@igniter-js/collections/adaptersBun-native apps (uses Bun.file, Bun.write)
BunRedisAdapter@igniter-js/collections/adaptersDistributed systems, multi-process apps
BunS3Adapter@igniter-js/collections/adaptersProduction deployments, object storage
MockAdapter@igniter-js/collections/adaptersTesting and CI environments

Quick Adapter Setup

import { NodeFsAdapter } from '@igniter-js/collections/adapters';

const adapter = new NodeFsAdapter();
import { BunFsAdapter } from '@igniter-js/collections/adapters';

const adapter = new BunFsAdapter();
import { BunRedisAdapter } from '@igniter-js/collections/adapters';

const adapter = new BunRedisAdapter({
  url: process.env.REDIS_URL,
  // Optional: key prefix for namespacing
  prefix: 'collections:',
});
import { BunS3Adapter } from '@igniter-js/collections/adapters';

const adapter = new BunS3Adapter({
  bucket: 'my-content-bucket',
  region: 'us-east-1',
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
});
import { IgniterCollectionMockAdapter } from '@igniter-js/collections/adapters';

const adapter = new IgniterCollectionMockAdapter();
// All data stored in memory — perfect for tests

Runtime Requirements

Node.js

package.json
{
  "engines": {
    "node": ">=18.0.0"
  }
}

The NodeFsAdapter uses node:fs/promises, node:path, and fast-glob. No native addons required.

Bun

package.json
{
  "engines": {
    "bun": ">=1.0.0"
  }
}

The BunFsAdapter uses Bun.file, Bun.write, and Bun.Glob for maximum performance. No Node.js APIs — pure Bun runtime.

Bun adapter exclusivity: BunFsAdapter, BunRedisAdapter, and BunS3Adapter rely on Bun-native APIs and will not work in Node.js. Use NodeFsAdapter for Node.js environments.

TypeScript Configuration

Collections requires TypeScript 5.6+ for full type inference. Ensure your tsconfig.json includes:

tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "moduleResolution": "bundler",
    "module": "ESNext",
    "target": "ES2022"
  }
}

The "bundler" module resolution is required for the @igniter-js/collections/adapters sub-path imports to resolve correctly.

Verifying Installation

Create a minimal script to verify everything works:

verify.ts
import { IgniterCollections, IgniterCollectionModel } from '@igniter-js/collections';
import { NodeFsAdapter } from '@igniter-js/collections/adapters';
import { z } from 'zod';

const Test = IgniterCollectionModel.create('test')
  .withPatterns(['.content/test/{id}.mdx'])
  .withSchema(z.object({ message: z.string() }))
  .build();

const docs = IgniterCollections.create()
  .withAdapter(new NodeFsAdapter())
  .withBasePath(process.cwd())
  .addCollection(Test)
  .build();

const result = await docs.test.create({
  data: { message: 'Installation verified!' }
});

console.log('✅ Collections is working:', result.id);

Run it:

npx tsx verify.ts
# ✅ Collections is working: a1b2c3d4-...

Next Steps

Defining Collections

Learn schema definition, file patterns, sub-collections, and templates.

CRUD Operations

Master create, read, update, delete, and count with type safety.

Adapters

Deep dive into each adapter and how to build your own.

Introduction

Type-safe ORM for content collections. Prisma-like API for Markdown, JSON, and YAML files with schema validation, lifecycle hooks, declarative views, and TypeScript-first configuration.

Defining Collections

Define type-safe content collections with Zod schemas, file patterns, sub-collections, templates, and custom ID generators.

On this page

InstallationChoosing an AdapterQuick Adapter SetupRuntime RequirementsNode.jsBunTypeScript ConfigurationVerifying InstallationNext Steps