🧩 Core

The core library is a minimal dependency framework for building Typescript based applications and libraries. It aims to provide some basic workflows and tools that can be used to create a variety of different types of projects.

🌐 Core Library Overview

⚙️ Configuration

Define and load structured configuration data from files, merge data from environment variables, and more.

📝 Logger

Advanced logging interface for detailed and customizable output, compatible with external libraries for specialized logging needs.

⏲️ Scheduler

Lifecycle-aware task scheduling, featuring flexible timing functions and robust error handling.

🔄 Lifecycle Hooks

Run commands at a variety of predetermined times during your application's boot or shutdown sequence.

⁉️ Testing Utilities

Convert your application into a testing module - append extra libraries and reconfigure modules to get the coverage you're looking for.

---

🚀 Setting up a new project

@digital-alchemy requires node20+ (node22 preferred)

The library exports modules as esmodules. Your tsconfig & package.json need to be correctly set up for imports.

1. For Home Assistant-focused applications, see the Automation Quickstart project for a quick setup solution.
2. The core library comes with everything needed to wire a basic application. Starting with strict mode TypeScript, and nice linting & prettier settings from the start is recommended.

📦 A basic app

Below are all the required parts to start an application.

main.ts

import { CreateApplication } from "@digital-alchemy/core";
import { Entry } from "./entry";

// Declare the application
export const MY_APP = CreateApplication({
  name: "my_app",
  services: { entry: Entry },
});

setImmediate(async () => await MY_APP.bootstrap());

// Add to loaded modules definitions
declare module "@digital-alchemy/core" {
  export interface LoadedModules {
    my_app: typeof MY_APP;
  }
}

entry.ts

import { TServiceParams } from "@digital-alchemy/core";

// a service is just a function that takes in `TServiceParams`
// may return a function, or an object if it wants
export function Entry({ logger, lifecycle }: TServiceParams) {
  lifecycle.onReady(() => logger.info("hello world!"));
}