@tmdjr/ngx-asset-manager

Standalone Angular 21.1.0 components for Ngx-Workshop MFEs: select existing assets, upload files, or combine both workflows. The workspace follows ngx-shared-headers: an independently packaged library under projects/ and a separate demo application.

Develop and verify

Use Node 22.12+ or Node 24 and npm 11.

npm ci
npm run build
npm test
npm run demo:build
npm start
npm run pack:library

The demo uses an in-memory adapter and does not require authentication or a running service. Uploads reset on reload. Build the library before starting the demo. The production demo uses /ngx-asset-manager/ as its base path for GitHub Pages.

Install in an MFE

After publishing:

npm install @tmdjr/ngx-asset-manager

Before publishing, install the tarball produced by npm run pack:library. Angular core/common peers and all workspace Angular packages are pinned to 21.1.0 to match the shell's requiredVersion: '21.1.0'. Consumers must use the same Angular runtime. The uploader's published @tmdjr/[email protected] provides public asset/folder types.

Register the adapter in the consumer's application configuration alongside its existing HTTP setup:

import {
  provideHttpClient,
  withInterceptorsFromDi,
} from "@angular/common/http";
import { provideAssetManager } from "@tmdjr/ngx-asset-manager";

export const appConfig = {
  providers: [
    provideHttpClient(withInterceptorsFromDi()),
    provideAssetManager(), // default gateway: /api/uploader
  ],
};

Preserve your existing HTTP interceptors; do not register a second HTTP client if the MFE already provides one. provideAssetManager({ apiUrl: '/another/uploader' }) overrides the endpoint. Requests send credentials. Angular 21.1.0's default provideHttpClient() uses XHR and supports upload progress. Consumers using withFetch() still upload successfully but see indeterminate progress.

import { Component } from "@angular/core";
import { Asset, AssetManagerComponent } from "@tmdjr/ngx-asset-manager";

@Component({
  selector: "app-course-assets",
  imports: [AssetManagerComponent],
  template: `
    <ngx-asset-manager
      title="Course images"
      view="compact"
      mode="both"
      [assetTypes]="['image']"
      [folderId]="courseFolderId"
      [uploadFolderId]="courseFolderId"
      uploadFolderLabel="Course images"
      accept="image/png,image/jpeg,.webp"
      [maxFileBytes]="5 * 1024 * 1024"
      (assetSelected)="selectAsset($event)"
      (uploaded)="onUploaded($event)"
    />
  `,
})
export class CourseAssets {
  // An existing folder ID from your application/service, not a folder name.
  courseFolderId = "507f1f77bcf86cd799439011";
  selectAsset(asset: Asset) {
    /* use asset._id or asset.storageUrl */
  }
  onUploaded(asset: Asset) {
    /* optional consumer side effect */
  }
}

The combined component refreshes its gallery after a successful upload. An uploaded asset can remain outside the visible gallery if its type or destination differs from the consumer's gallery filters. It still emits uploaded.

Components and inputs

AssetManagerComponent (ngx-asset-manager) composes AssetGalleryComponent (ngx-asset-gallery) and AssetUploadComponent (ngx-asset-upload). Import any of them independently.

| Input | Default | Applies to | Behavior | | ------------------- | ----------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | view | 'full' | All | 'compact': small thumbnails and minimal upload UI; 'full': larger cards, asset details, folder browsing and optional upload name/description. | | mode | 'both' | Manager | 'gallery', 'upload', or 'both'. | | title | 'Asset library' | Manager | Section title and accessible label. | | assetTypes | [] | Gallery, manager | Allowed gallery categories: image, video, audio, document, other, record. Empty means all. | | folderId | undefined | Gallery, manager | undefined: all folders; null: root only; string: exact folder only. Explicit scope disables folder browsing. | | includeArchived | false | Gallery, manager | Include archived assets when true. | | browseFolders | true | Gallery, manager | Show a folder selector in the full view when the consumer has not specified a folder. | | refreshToken | 0 | Gallery, manager | Change this number to reload after an external update. | | uploadFolderId | null | Upload, manager | Consumer-controlled destination for new uploads; null is root. Independent of gallery scope. | | uploadFolderLabel | '' | Manager | Friendly upload destination label. Direct upload component calls this input folderLabel. | | accept | '' | Upload, manager | Comma-separated MIME types, MIME wildcards, or filename extensions; empty allows all. Applied to the file picker and validated before sending. | | maxFileBytes | 26214400 | Upload, manager | File limit, capped at the uploader service's 25 MiB maximum. |

assetSelected emits the selected Asset from gallery/manager. uploaded emits the server-returned Asset from upload/manager. uploadFailed emits the error from upload/manager. Invalid files never reach the upload adapter. Files remain selected after server errors for retry. A single file uploads at a time. Name and description respect the uploader's 120/2000-character limits.

Gallery category filtering and upload restrictions are separate controls. Configure both when, for example, a consumer should show and upload only images. File picker/MIME checks are client UX; the service remains responsible for authorization and content validation. Folder filters do not grant or enforce permissions.

No folder create/rename/delete, asset metadata editing, deletion, archiving, or movement operations are exposed. Full view supports browsing and selection, not administration.

Custom backend or consumer-owned data

Provide an AssetDataSource implementation under ASSET_DATA_SOURCE instead of provideAssetManager():

import { ASSET_DATA_SOURCE, AssetDataSource } from "@tmdjr/ngx-asset-manager";

// Your service implements listAssets(query), listFolders(), and upload(request).
// upload emits Angular HttpEvents and ends with HttpResponse<Asset>.
const providers = [
  { provide: ASSET_DATA_SOURCE, useExisting: MyAssetDataSource },
];

This supports alternative gateways, mock data, and consumer-owned authentication. The library cancels obsolete gallery requests on scope changes and unsubscribes when destroyed. Gallery filtering is also applied locally, so custom adapters cannot accidentally show assets outside the requested scope. Image previews require READY storage and an HTTP(S) URL or same-origin path; other assets show type placeholders. URL access still depends on storage permissions. Styles use the shell's --mat-sys-* tokens with fallback values and require no Angular Material runtime dependency.

Federation

Use the shell's existing Angular singleton configuration with requiredVersion: '21.1.0'. This is an npm Angular library, not a remote MFE. Import its public package entry point. If the host and remotes share this package, add it using the established shared-package convention; keep the shell and consumer package versions aligned.

Release

CI runs the library tests, production library build, and demo build. The publishing workflow is manual and publishes the version in projects/ngx-asset-manager/package.json from main using npm trusted publishing (OIDC). Configure the npm trusted publisher for Ngx-Workshop/ngx-asset-manager, workflow publish.yml, and package @tmdjr/ngx-asset-manager before running it. If the package does not yet exist on npm, a maintainer must make the first authenticated publish, then configure the trusted publisher for subsequent releases. See npm trusted publishing. Increase the library version before subsequent releases. No npm token is stored in the repository.

The initial package is 21.1.0. npm pack ./dist/ngx-asset-manager creates a distributable for integration testing without publishing. A real service smoke test requires a consumer session and a reachable uploader gateway; the demo and automated tests use mock data/HTTP.

Compatibility limitation

The October 4, 2026 dependency audit reports advisories affecting the explicitly required Angular 21.1.0 runtime and its build tools. Version upgrades require coordination with the shell singleton requirement. The adapter disables HTTP transfer caching for credentialed asset/folder reads. Audit findings are not a clean security bill for this pinned toolchain.