Skip to content

Installation

Jump to bottom
Miguel Guevara edited this page Jan 9, 2026 · 1 revision

Installation Guide

Complete installation and configuration guide for @arcaelas/dynamite

This guide covers everything you need to install, configure, and verify @arcaelas/dynamite in your project.

Prerequisites

Before installing @arcaelas/dynamite, ensure your development environment meets these requirements:

Node.js Version

  • Node.js 16.x or higher (18.x or 20.x recommended)
  • npm 7.x or higher or yarn 1.22.x or higher

Check your versions:

node --version  # Should be >= 16.0.0
npm --version   # Should be >= 7.0.0

AWS Account Requirements

You'll need one of the following:

  1. AWS Account with DynamoDB access

    • Valid AWS credentials (Access Key ID and Secret Access Key)
    • IAM permissions for DynamoDB operations
    • AWS region selection (e.g., us-east-1, eu-west-1)

  2. DynamoDB Local for development (recommended for testing)

    • Docker installed (easiest method)
    • Or Java Runtime Environment 8.x or higher

TypeScript (Optional but Recommended)

  • TypeScript 5.x or higher for full type safety
  • Configure tsconfig.json:
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Installation

Install via npm

# Install @arcaelas/dynamite
npm install @arcaelas/dynamite

# Install peer dependencies
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb

Install via yarn

# Install @arcaelas/dynamite
yarn add @arcaelas/dynamite

# Install peer dependencies
yarn add @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb

Verify Installation

After installation, verify the packages are installed correctly:

npm list @arcaelas/dynamite @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb

DynamoDB Setup

Option 1: DynamoDB Local (Development)

DynamoDB Local is perfect for development and testing without AWS costs.

Using Docker

# Pull and run DynamoDB Local
docker run -d \
  -p 8000:8000 \
  --name dynamodb-local \
  amazon/dynamodb-local

Using Docker Compose

Create a docker-compose.yml file:

version: '3.8'

services:
  dynamodb-local:
    image: amazon/dynamodb-local
    container_name: dynamodb-local
    ports:
      - "8000:8000"
    command: ["-jar", "DynamoDBLocal.jar", "-sharedDb"]

Start the service:

docker-compose up -d

Verify DynamoDB Local is Running

curl http://localhost:8000

Option 2: AWS DynamoDB (Production)

For production deployment, use AWS DynamoDB.

Set Up AWS Credentials

Method 1: AWS CLI Configuration

aws configure
# Enter your credentials when prompted:
# AWS Access Key ID: YOUR_ACCESS_KEY_ID
# AWS Secret Access Key: YOUR_SECRET_ACCESS_KEY
# Default region name: us-east-1

Method 2: Environment Variables

export AWS_ACCESS_KEY_ID="your-access-key-id"
export AWS_SECRET_ACCESS_KEY="your-secret-access-key"
export AWS_REGION="us-east-1"

Method 3: IAM Roles (For EC2, Lambda, ECS)

Use IAM roles instead of credentials when running on AWS infrastructure.

Basic Configuration

Create Configuration File

config/database.ts (TypeScript)

import { Dynamite } from "@arcaelas/dynamite";
import { User, Order } from "./models";

export async function ConfigureDatabase() {
  const config = process.env.NODE_ENV === "development"
    ? {
        region: "us-east-1",
        endpoint: "http://localhost:8000",
        tables: [User, Order],
        credentials: { accessKeyId: "test", secretAccessKey: "test" }
      }
    : {
        region: process.env.AWS_REGION || "us-east-1",
        tables: [User, Order],
        credentials: {
          accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
          secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!
        }
      };

  const dynamite = new Dynamite(config);
  await dynamite.connect();

  return dynamite;
}

Environment Variables Setup

Create a .env file:

# Development
NODE_ENV=development
DYNAMODB_ENDPOINT=http://localhost:8000

# Production
# NODE_ENV=production
# AWS_REGION=us-east-1
# AWS_ACCESS_KEY_ID=your-access-key-id
# AWS_SECRET_ACCESS_KEY=your-secret-access-key

Install dotenv:

npm install dotenv

Load environment variables:

import dotenv from "dotenv";
dotenv.config();

import { ConfigureDatabase } from "./config/database";
ConfigureDatabase();

Define Your First Model

models/user.ts

import {
  Table,
  PrimaryKey,
  Default,
  CreatedAt,
  UpdatedAt,
  CreationOptional,
  NotNull
} from "@arcaelas/dynamite";

export class User extends Table<User> {
  @PrimaryKey()
  @Default(() => crypto.randomUUID())
  declare id: CreationOptional<string>;

  @NotNull()
  declare name: string;

  @NotNull()
  declare email: string;

  @Default(() => "customer")
  declare role: CreationOptional<string>;

  @CreatedAt()
  declare created_at: CreationOptional<string>;

  @UpdatedAt()
  declare updated_at: CreationOptional<string>;
}

Verification

Test Database Connection

test-connection.ts

import dotenv from "dotenv";
dotenv.config();

import { Dynamite, Table, PrimaryKey, Default } from "@arcaelas/dynamite";

class TestModel extends Table<TestModel> {
  @PrimaryKey()
  @Default(() => "test-id")
  declare id: string;
}

async function TestConnection() {
  try {
    const dynamite = new Dynamite({
      region: "us-east-1",
      endpoint: "http://localhost:8000",
      tables: [TestModel],
      credentials: { accessKeyId: "test", secretAccessKey: "test" }
    });
    await dynamite.connect();

    console.log("✓ Connection test passed");
  } catch (error) {
    console.error("✗ Connection failed:", error);
  }
}

TestConnection();

Run:

npx tsx test-connection.ts

Troubleshooting

Module Not Found

# Verify installation
npm list @arcaelas/dynamite

# Reinstall
npm install @arcaelas/dynamite --save

Cannot Connect to DynamoDB Local

# Check if running
docker ps | grep dynamodb-local

# Start if not running
docker run -d -p 8000:8000 amazon/dynamodb-local

TypeScript Decorator Errors

Update tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Next Steps

Need Help? Open an issue on GitHub

Clone this wiki locally