Skip to content
Fractary Developers

Forge Overview

Forge: Asset Management SDK

Section titled “Forge: Asset Management SDK”

Core SDK for managing project assets across multiple version control systems.

Forge is a powerful SDK for managing project assets (bundles and starters) with a plugin-based resolver architecture that supports GitHub, GitLab, Bitbucket, and custom source control providers.

Core SDK

Section titled “Core SDK”

The Forge SDK (@fractary/forge) provides reusable components for asset resolution, caching, configuration management, and file operations.

Terminal window
npm install @fractary/forge

Key Features

Section titled “Key Features”

🔌 Plugin-Based Resolvers

Section titled “🔌 Plugin-Based Resolvers”

Extensible architecture for multiple VCS providers. Register custom resolvers for any source control system.

🌐 Multi-VCS Support

Section titled “🌐 Multi-VCS Support”

Built-in support for GitHub, static catalogs, and local/embedded assets. Add support for GitLab, Bitbucket, or custom providers.

📦 Asset Management

Section titled “📦 Asset Management”

Manage bundles and starters with ownership rules and intelligent file filtering.

💾 Smart Caching

Section titled “💾 Smart Caching”

Intelligent caching with configurable TTL:

  • 1 hour for branches (frequently updated)
  • 24 hours for releases (stable versions)

🔧 Flexible Configuration

Section titled “🔧 Flexible Configuration”

Multi-source configuration with global and project-level settings.

📝 TypeScript First

Section titled “📝 TypeScript First”

Full TypeScript support with comprehensive type definitions and subpath exports.

Quick Start

Section titled “Quick Start”
import { ResolverManager, GitHubResolver } from '@fractary/forge';


// Initialize resolver manager
const manager = new ResolverManager();


// Register GitHub resolver
manager.registerResolver(new GitHubResolver({
  token: process.env.GITHUB_TOKEN,
  defaultOrg: 'fractary'
}));


// Resolve and fetch an asset
const asset = await manager.resolveAsset('fractary/forge-bundle-auth@v1.0.0');


console.log(asset.manifest.name);
console.log(`${asset.files.size} files`);

Architecture

Section titled “Architecture”
┌─────────────────────────────────────────┐
│        ResolverManager                  │
│  (Routes requests to resolvers)         │
└────┬───────────┬────────────┬───────────┘
     │           │            │
     ▼           ▼            ▼
┌──────────┐ ┌────────┐ ┌─────────┐
│ GitHub   │ │Catalog │ │  Local  │
│Resolver  │ │Resolver│ │ Resolver│
└──────────┘ └────────┘ └─────────┘

Supported Resolvers

Section titled “Supported Resolvers”

GitHub Resolver

Section titled “GitHub Resolver”

Fetch assets from GitHub repositories via API:

  • Tarball download and extraction
  • Smart caching (1hr for branches, 24hr for releases)
  • File filtering based on manifest patterns
  • Authentication via GitHub tokens

Catalog Resolver

Section titled “Catalog Resolver”

Static JSON catalog for asset discovery:

  • Multi-catalog management
  • Asset search and discovery
  • Offline support with disk caching

Local Resolver

Section titled “Local Resolver”

Local filesystem and embedded assets:

  • file:// URL support
  • Embedded asset loading
  • Development and testing

Custom Resolvers

Section titled “Custom Resolvers”

Implement the IResolver interface for custom sources like:

  • GitLab
  • Bitbucket
  • S3 buckets
  • Custom registries

Asset Identifier Formats

Section titled “Asset Identifier Formats”
// Explicit resolver prefix
'github:owner/repo@ref'          → GitHubResolver
'catalog:asset-id'               → CatalogResolver
'file:///path/to/asset'          → LocalResolver


// Default resolver (configured)
'owner/repo@ref'                 → Default resolver

Configuration

Section titled “Configuration”
import { ConfigManager } from '@fractary/forge';


const configMgr = new ConfigManager();
const config = await configMgr.loadGlobalConfig();


// Configure multiple resolvers
config.resolvers.github = {
  token: process.env.GITHUB_TOKEN,
  defaultOrg: 'fractary'
};


config.resolvers.default = 'github';

Module Exports

Section titled “Module Exports”

The SDK provides subpath exports for granular imports:

import { ResolverManager } from '@fractary/forge';
import { GitHubResolver } from '@fractary/forge/resolvers';
import { ForgeConfig } from '@fractary/forge/types';
import { ConfigManager } from '@fractary/forge/config';
import { CacheManager } from '@fractary/forge/cache';
import { ForgeError } from '@fractary/forge/errors';

Use Cases

Section titled “Use Cases”
  • Bundle Distribution - Distribute pre-configured component bundles
  • Project Scaffolding - Initialize new projects from starter templates
  • Multi-Repo Management - Sync assets across multiple repositories
  • Development Tooling - Build CLIs and automation tools

Status

Section titled “Status”

Current Version: 1.0.0 Status: Production Ready License: MIT

The SDK is complete and published to GitHub Package Registry. Additional features planned for v1.1.0.

Next Steps

Section titled “Next Steps”
Section titled “Related Projects”
  • forge-cli - CLI tool built on Forge SDK
  • forge-bundle-* - Pre-built bundles for common use cases
  • forge-catalog - Public catalog of Forge assets