Skip to main content

Configuration

The only supported ways to define configuration are javascript or typescript files (transpiled through ts-node).

Reference​

collections​

  • Type: Record<string, AssetDescriptor | AssetDescriptorObject>
  • Required: Yes

Defines collections of assets along with configuration for them like storage, requirements, processors and other options.

Asset descriptor can be defined as object

import {Configuration} from '@farbor/server';

export const config: Configuration = {
  collections: {
    image: {
      requirements: [
        new RequirementFileSize({start: 1_000_000})
      ]
    }
  }
}

or as an instance of AssetDescriptorBuilder class

import {AssetDescriptorBuilder, RequirementFileSize, Configuration} from '@farbor/server';

export const config: Configuration = {
  collections: {
    image: new AssetDescriptorBuilder()
      .addRequirement(
        new RequirementFileSize({start: 1_000_000})
      )
  }
}

Using AssetDescriptorBuilder class is recommended for more complex configurations with conditions as it allows using method chaining through conditional builder pattern.

import {AssetDescriptor} from '@farbor/server';
import {isProduction} from '@pallad/app-env';

export const config: Configuration = {
  collections: {
    image: new AssetDescriptor()
      .runIf(isProduction, (descriptor) => { // add filesize requirement only for production
        descriptor.addRequirement(new RequirementFileSize({
          start: 1_000_000
        }))
      })
  }
}

In both scenarios, if any of parameters is not defined at asset descriptor level then it is taken from collectionsDefaults.

collectionsDefaults​

Defines default attributes for asset descriptors defined in collections. If any of the attributes is not defined at asset descriptor level then it is taken from here.

collections.*.storage, collectionsDefaults.storage​

  • Type: AssetStorage
  • Required: No / Yes (for asset descriptor) if default is not provided
  • Default: none

Defines storage for assets.

In case of collectionDefaults.storage provided storage is not used directly but each asset descriptor receives a copy of it (created through createNewStorageForCollection).

collections.*.processedStorage, collectionsDefaults.processedStorage​

  • Type: ProcessedAssetStorage
  • Required: No / Yes (for asset descriptor) if default is not provided
  • Default: none

Defines storage for processed assets in collection.

In case of collectionDefaults.processedStorage provided storage is not used directly but each collection asset descriptor receives a copy of it (created through createNewStorageForCollection).

collections.*.requirements, collectionsDefaults.requirements​

  • Type: Array<Requirement>
  • Required: No
  • Default: []

List of requirements that assets in collection must meet upon saving.

collections.*.visibilityOptions, collectionsDefaults.visibilityOptions​

  • Type: Visibility | {fallback: Visibility, allowed: Visibility[]}
  • Required: No
  • Default {fallback: 'public', allowed: ['public', 'private']}

Where type Visibility = 'public' | 'private'

Possible visibility for assets in collection.

  • fallback - default visibility applied to uploaded file if not explicitly set
  • allowed - list of allowed visibilities for assets in collection

You can just provide visibility as a string which translates to:

  • private = {fallback: 'private', allowed: ['private']}
  • public = {fallback: 'public', allowed: ['public']}

Available presets:

  • AssetVisibilityOptionsPreset.PRIVATE_ONLY - {fallback: 'private', allowed: ['private']}
  • AssetVisibilityOptionsPreset.PUBLIC_ONLY - {fallback: 'public', allowed: ['public']}
  • AssetVisibilityOptionsPreset.PRIVATE_DEFAULT - {fallback: 'private', allowed: ['public', 'private']}
  • AssetVisibilityOptionsPreset.PUBLIC_DEFAULT - {fallback: 'public', allowed: ['public', 'private']}

collections.*.preProcessDescriptors, collectionsDefaults.preProcessDescriptors​

  • Type: Array<PreProcessDescriptor>
  • Required: No
  • Default: collectionsDefaults.preProcessDescriptors

List of processor descriptors applied to assets before saving.

secretKeyStorage​

Defines storage for secret keys used for signing and verifying tokens.

Example configuration​

import path from "node:path";

import {
  RequirementImageDimension,
  RequirementImageAspectRatio,
  processor as processorSharp,
} from "@farbor/processor-sharp";
import {
  AssetExtension,
  Configuration,
  RequirementFileSize,
  RequirementMimeType,
} from "@farbor/server";
import { AssetStorage, ProcessedAssetStorage } from "@farbor/storage-filesystem";

// eslint-disable-next-line import/no-default-export
const config: Configuration = {
  collections: {
    image: {
      requirements: [
        // allow only images
        RequirementMimeType.images(),
        // image need to be at least 100x100
        new RequirementImageDimension({
          width: { start: 100 },
          height: { start: 100 },
        }),
        // max file size 100MB
        new RequirementFileSize({
          end: 104_857_600,
        }),
      ],
    },
    avatar: {
      requirements: [
        // allow only images
        RequirementMimeType.images(),
        // avatar must be square of exact size (this is stupid but just for demo purposes)
        new RequirementImageDimension({
          width: 800,
          height: 800,
        }),
        // aspect ratio of image 1:1
        new RequirementImageAspectRatio([1, 1]),
      ],
    },
    icon: {
      requirements: [
        // only SVG files
        new RequirementMimeType([AssetExtension.Preset.SVG]),
        // dimensions of at least 32x32
        new RequirementImageDimension({
          width: { start: 32 },
          height: { start: 32 },
        }),
      ],
    },
    document: {
      // accept only documents
      requirements: [new RequirementMimeType([AssetExtension.Preset.PDF])],
    },
    report: {
      // accept only csv files
      requirements: [new RequirementMimeType([AssetExtension.Preset.CSV])],
      // all of the files can only be private
      visibilityOptions: "private",
    },
  },
  collectionsDefaults: {
    // all assets are stored under `storage` directory (and subdirectory for each collection)
    storage: AssetStorage.fromUncheckedRootDirectory(path.join(__dirname, "../storage")),
    // all processed assets are stored under `processed-storage` directory (and subdirectory for each collection)
    processedStorage: ProcessedAssetStorage.fromUncheckedRootDirectory(
      path.join(__dirname, "../processed-storage")
    ),
    // default processors available for all collections
    processors: [processorSharp],
  },
};
export default config;