Installation

GitHub Packages Setup

S3WORM is published to GitHub Packages under the @decoperations scope. You need a .npmrc file that points the scope to the GitHub registry and includes an auth token.

Create or update .npmrc in your project root (or ~/.npmrc for global access):

@decoperations:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

The GITHUB_TOKEN must have read:packages scope. You can create a personal access token at github.com/settings/tokens.

Install Packages

The main package includes the ORM client, entity system, CLI, and all runtime code:

pnpm add @decoperations/s3worm

With npm or yarn:

npm install @decoperations/s3worm
yarn add @decoperations/s3worm

The package bundles the AWS SDK S3 client as a dependency -- you do not need to install it separately.

Requirements

TypeScript Configuration

S3WORM is written in TypeScript and ships type declarations. For the best experience, enable strict mode in your tsconfig.json:

{
  "compilerOptions": {
    "strict": true,
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

Key settings:

• strict: true -- Enables full type checking for entity fields and repository generics.
• target: ES2020 or later -- Required for async iteration and Uint8Array APIs used internally.
• moduleResolution: "bundler" -- Works best with the package's conditional exports. Use "node16" or "nodenext" if you are not using a bundler.

Entry Points

S3WORM ships three entry points for different runtime environments:

The entry points include runtime guards that throw if used in the wrong environment:

// Server-only code -- throws in browser/edge
import { TemplateAdapter } from "@decoperations/s3worm/server";

// Edge-safe code -- throws in Node.js
import { Entity, getS3Worm } from "@decoperations/s3worm/edge";

// Universal -- works everywhere
import { S3Worm, Entity, Repository } from "@decoperations/s3worm";

Vite Setup

Vite handles the conditional exports automatically. No extra configuration is needed for the default or edge entry points:

// vite.config.ts
import { defineConfig } from "vite";

export default defineConfig({
  // S3WORM works out of the box with Vite's default settings.
  // If you need the server entry point in SSR mode:
  ssr: {
    noExternal: ["@decoperations/s3worm"],
  },
});

For client-side usage, import from the main entry point. Vite will resolve the browser condition in the package's exports map:

import { S3Worm } from "@decoperations/s3worm";

Next.js Setup

In Next.js, use the server entry point in API routes and Server Components, and the main entry point in Client Components:

// app/api/data/route.ts (server)
import { S3Worm } from "@decoperations/s3worm/server";

export async function GET() {
  const worm = new S3Worm({
    bucket: process.env.S3_BUCKET!,
    endpoint: process.env.S3_ENDPOINT!,
    credentials: {
      accessKeyId: process.env.S3_ACCESS_KEY!,
      secretAccessKey: process.env.S3_SECRET_KEY!,
    },
  });

  const data = await worm.read("config/settings.json");
  return Response.json(data);
}

// components/uploader.tsx (client)
"use client";
import { S3Worm } from "@decoperations/s3worm";

For middleware or edge routes, use the edge entry point:

// middleware.ts
import { getS3Worm } from "@decoperations/s3worm/edge";

Node.js Setup (No Bundler)

For plain Node.js projects without a bundler, import from the main or server path. The package supports both ESM and CommonJS:

// ESM
import { S3Worm } from "@decoperations/s3worm";

// CommonJS
const { S3Worm } = require("@decoperations/s3worm");

If you use ts-node or tsx for development, ensure your tsconfig.json uses "module": "ESNext" with "moduleResolution": "bundler" or "nodenext".

Verify Installation

Run a quick smoke test to confirm everything is wired up:

import { S3Worm, Entity } from "@decoperations/s3worm";

// Entity class check
class TestEntity extends Entity {
  name = "test";
  static getBasePath() { return "test"; }
}

console.log(new TestEntity().getPath()); // "test/test.json" (or similar with auto ID)

// Client instantiation check (does not make network calls)
const worm = new S3Worm({
  bucket: "test-bucket",
  endpoint: "https://localhost:9000",
  credentials: {
    accessKeyId: "minioadmin",
    secretAccessKey: "minioadmin",
  },
});

console.log(worm.getBucketName()); // "test-bucket"
console.log("S3WORM is installed correctly.");